graphql-server

A GraphQL server implementation written in NodeJS/Typescript. It uses the standard graphql library to receive GraphQL requests and send back appropriate responses.

Deprecated: This library will no longer be maintained. Use graphql-yoga or graphql-http instead!

Installation

npm install --save @dreamit/graphql-server

TypeScript declarations are provided within the project.

Compatibility

The following table shows which version of graphql-js, @dreamit/graphql-server-base and @dreamit/funpara are compatible with which version of @dreamit/graphql-server. As @dreamit/graphql-server defines them as peerDependency you might want to choose a fitting version used in your project and by other libraries depending on them.

graphql-js version	graphql-server version	graphql-server-base version	funpara version	Github branch	Development Status
^15.2.0	1.x	n.a.	n.a.	legacy-graphql15	end of life
^16.0.0	2.x	n.a.	n.a.	legacy-server-v2	end of life
^16.0.0	3.x	^1.0.1	n.a.	legacy-server-v3	end of life
^16.0.0	4.x	^2.7	^1.0	legacy-server-v4	maintenance
^16.0.0	5.x	^3.1	^1.0	main	active

Features

• Creates GraphQL responses
• Can be used with many webservers (see Webserver compatibility).
• Supports both application/graphql-response+json and application/json response formats
• Uses out-of-the-box default options to ease use and keep code short
• Provides hot reloading for schema and options
• Provides out-of-the-box metrics for GraphQLServer
• Provides option to validate response against StandardSchemaV1 compliant schema.
• Uses only 3 peerDependencies: graphql-js version 16, graphql-server-base version 3 and funpara version 1 (no other production dependencies)

Handling and executing requests

GraphQLServer provides the function handleRequest to handle and execute requests. Depending on the provided parameters different actions will be executed in order to send or return the ExecutionResult

• request: If the request is a GraphQLServerRequest the async extractInformationFromRequest function will be used to extract information from the request (url and/or body) and be available as GraphQLRequestInfo. If the request already is a GraphQLRequestInfo this information will be used without extracting information from the server request.
• response: If a response is provided (i.e. not undefined), a response will be sent using sendResponse function and the GraphQLExecutionResult will be returned. If response is undefined, no response will be sent and the GraphQLExecutionResult will be returned.

class GraphQLServer {
    async handleRequest(
        request: GraphQLServerRequest | GraphQLRequestInfo,
        response?: GraphQLServerResponse,
    ): Promise<GraphQLExecutionResult> {}
}

Use cases

The handleRequest function can be used for many use cases. The following part lists some use cases with a short description. It is possible to use handleRequest with different parameters with a single GraphQLServer instance, e.g. when using a webserver with websockets or messaging.

• handleRequest with GraphQLServerRequest and GraphQLServerResponse: Use as webserver middleware. Create an instance of GraphQLServer and use the request and response provided by the webserver as parameters. You might need to wrap one or both values, see Webserver compatibility
• handleRequest with GraphQLRequestInfo: Use for flexible GraphQL execution, e.g. for websockets or messaging. Create an instance of GraphQLServer and given a GraphQLRequestInfo the request can be executed and the returned GraphQLExecutionResult can be used for multiple purposes like sending a message or responding to a websocket request.
• handleRequest with GraphQLServerRequest: Use as alternative webserver middleware or if custom actions should be done before sending back a response. Create an instance of GraphQLServer and use the request provided by the webserver as parameter for this function. You might need request values, see Webserver compatibility. The returned GraphQLExecutionResult can be used to execute custom logic with the result and/or prepare or send a response.
• handleRequest with GraphQLRequestInfo and GraphQLServerResponse: Use if a GraphQLRequestInfo is available and a response should be sent from this request.

Usage as webserver middleware

You can create a new instance of GraphQLServer with the options necessary for your tasks. The handleRequest function of the GraphQLServer can be integrated with many fitting webservers.

Note regarding POST requests:

graphql-server version 5 and higher tries to extract the request information from the request.body field or response.text function if request.body is undefined. Some webserver frameworks like Express might need a fitting body parser in order to populate this body field.

• parse body as string/text (recommended): graphql-server will handle reading content and parsing it to JSON.
• parse body as object/JSON: graphql-server will read JSON and try to assign it to matching fields. This might cause FetchErrors if the body contains invalid JSON. We recommend using text parsers instead so graphql-server can respond with a fitting GraphQL error response if JSON is invalid.

const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({ schema: someExampleSchema })
graphQLServerExpress.use(bodyParser.text({ type: '*/*' }))
graphQLServerExpress.all('/graphql', (req, res) => {
    return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.listen({ port: graphQLServerPort })
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)

GraphQLServer provides default values and behavior out of the box. It is recommended to at least provide a schema so the request won't be rejected because of a missing/invalid schema. When using it with a local schema it is recommended to provide a rootValue to return a fitting value. Examples for these requests can be found in the integration test in the GraphQLServer.integration.test.ts class in the tests/server folder.

Setting response format

GraphQLServer supports two response formats:

• application/json: Default, used for legacy GraphQL server and client support. Will return status code 200 for some error cases like parsing and validation errors.
• application/graphql-response+json: New format recommended by GraphQL specification. Will return status code 400 for all error cases.

Which response format will be used depends on the set accept request header. If the header is not set, set to application/json or application/json with a higher priority this format will be used. application/graphql-response+json will be used only if it is set in accept header or set with higher priority then application/json.

Schema validation and disabling Introspection

Validation rules can be used to define how the GraphQLServer should behave when validating the request against the given schema. To ease the use GraphQLServer uses the specifiedRules from graphql-js library. If you don't want to use the default validation rules you can overwrite them by setting defaultValidationRules option to [].

Warning! Setting both defaultValidationRules and customValidationRules options to [] will disable validation. This might result in unexpected responses that are hard to use for API users or frontends.

import { NoSchemaIntrospectionCustomRule } from 'graphql'

const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({
    schema: someExampleSchema,
    defaultValidationRules: [],
})
graphQLServerExpress.use(bodyParser.text({ type: '*/*' }))
graphQLServerExpress.all('/graphql', (req, res) => {
    return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.listen({ port: graphQLServerPort })
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)

If you want to define custom validation rules you can use the customValidationRules option (e.g. to handle introspection like shown in the example below).

Introspection can be used to get information about the available schema. While this may be useful in development environments and public APIs you should consider disabling it for production if e.g. your API is only used with a specific matching frontend.

Introspection can be disabled by adding the NoSchemaIntrospectionCustomRule from the graphql-js library to the customValidationRules option.

import { NoSchemaIntrospectionCustomRule } from 'graphql'

const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({
    schema: someExampleSchema,
    customValidationRules: [NoSchemaIntrospectionCustomRule],
})
graphQLServerExpress.use(bodyParser.text({ type: '*/*' }))
graphQLServerExpress.all('/graphql', (req, res) => {
    return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.listen({ port: graphQLServerPort })
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)

Response validation

The GraphQL response can be validated using the responseStandardSchema option. It accepts a StandardSchemaV1 and will, when using sendResponse, put found issues into the response as GraphQLErrors. By default noOpStandardSchema is used and returns the value and no issues. To validate the response a StandardSchemaV1 compliant schema like @dreamit/graphql-std-schema can be used.

import { graphQLResponseSchema } from '@dreamit/graphql-std-schema'

const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({
    responseStandardSchema: graphQLResponseSchema(),
    schema: someExampleSchema,
})
graphQLServerExpress.use(bodyParser.text({ type: '*/*' }))
graphQLServerExpress.all('/graphql', (req, res) => {
    return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.listen({ port: graphQLServerPort })
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)

Schema hot reload

Hot reload of the GraphQL schema can be used to update the existing schema to a new version without restarting the GraphQL server, webserver or whole application. When setting a new schema it will be used for the next incoming request while the old schema will be used for requests that are being processed at the moment. Hot reloading is especially useful for remote schemas that are processed in another application like a webservice.

The schema can be changed simply by calling setSchema in the GraphQLServer instance. In the example below a second route is used to trigger a schema update.

const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({ schema: someExampleSchema })
graphQLServerExpress.use(bodyParser.text({ type: '*/*' }))
graphQLServerExpress.all('/graphql', (req, res) => {
    return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.all('/updateme', (req, res) => {
    const updatedSchema = someMagicHappened()
    customGraphQLServer.setSchema(updatedSchema)
    return res.status(200).send()
})
graphQLServerExpress.listen({ port: graphQLServerPort })
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)

Metrics

There are 2 builtin MetricsClient implementations available.

• SimpleMetricsClient: Used as default MetricsClient. Provides GraphQLServer related metrics without but does not provide NodeJS metrics like cpu and memory usage.
• NoMetricsClient: Does not collect any metrics. Can be used to disable metrics collection/increase performance.

The SimpleMetricsClient provides three custom metrics for the GraphQL server:

• graphql_server_availability: Availability gauge with status 0 (unavailable) and 1 (available)
• graphql_server_request_throughput: The number of incoming requests
• graphql_server_errors: The number of errors that are encountered while running the GraphQLServer. The counter uses the errorName field as label so errors could be differentiated. At the moment the following labels are available and initialized with 0:
  • FetchError
  • GraphQLError
  • SchemaValidationError
  • MethodNotAllowedError
  • InvalidSchemaError
  • MissingQueryParameterError
  • ValidationError
  • SyntaxError
  • IntrospectionDisabledError

A simple metrics endpoint can be created by using getMetricsContentType and getMetrics functions from the GraphQLServer instance. In the example below a second route is used to return metrics data.

const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({ schema: someExampleSchema })
graphQLServerExpress.use(bodyParser.text({ type: '*/*' }))
graphQLServerExpress.all('/graphql', (req, res) => {
    return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.get('/metrics', async (req, res) => {
    return res
        .contentType(customGraphQLServer.getMetricsContentType())
        .send(await customGraphQLServer.getMetrics())
})
graphQLServerExpress.listen({ port: graphQLServerPort })
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)

CORS requests

The GraphQLServer does not handle CORS requests on its own. It is recommended to handle this on the webserver level, e.g. by using cors library with an Express webserver like in the example below.

const graphQLServerPort = 3592
const graphQLServerExpress = express()
graphQLServerExpress.use(cors())
const customGraphQLServer = new GraphQLServer({ schema: someExampleSchema })
graphQLServerExpress.use(bodyParser.text({ type: '*/*' }))
graphQLServerExpress.all('/graphql', (req, res) => {
    return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.listen({ port: graphQLServerPort })
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)

Webserver compatibility

The handleRequest function works with webservers that provide a fitting request and response object that matches GraphQLServerRequest and GraphQLServerResponse interface. As Express (since version 2.x) matches both no further adjustment is necessary. If one or both objects do not match GraphQLServerRequest and GraphQLServerResponse it might still be possible to map the webserver request and response objects to these interfaces.

In the following table a list of webserver frameworks/versions can be found that are able to run GraphQLServer. The Version column shows the version of the webserver framework we tested GraphQLServer version 4 with.
If the request and/or response has to be mapped it is noted in the Mapping column. There is a code examples on how to use handleRequest without providing a GraphQLServerResponse and sending the response with the functionality provided by the webserver.

Framework/Module	Version	Mapping	Example
Express	> = 2.x	none	Express example
fastify	5.3.2	none	Fastify example
hapi	21.4.0	request, no response	hapi example
Koa	3.0.0	response	Koa example
Next.js	15.3.1	response	Next.js example
Nitro	4.9.5	request	Nitro example
NodeJS http	22.x	request	NodeJS http example
Socket.IO	4.7.5	response	Socket.IO example
gRPC	1.8.14	no response	gRPC example
Deno	1.42.1	request, no response	Deno HTTP example
Bun	1.1.0	request, no response	Bun example

GraphQLServerRequest and GraphQLServerResponse interfaces

The GraphQLServerRequest and GraphQLServerResponse are available in the @dreamit/graphql-server-base module. This allows extensions such as custom Logger or MetricsClient implementations to implement these interfaces without defining @dreamit/graphql-server as dependency.

Working with context function

GraphQLServer, like many GraphQL libraries, uses a context function to create a context object of type Record<string, unknown> that is available during the whole request execution process. This can for example be used to inject information about request headers or adjust responses. An example can be found in the CustomSendResponse.integration.test.ts class in the test/server folder.

export interface GraphQLServerOptions {
    contextFunction: (contextParameters: {
        serverOptions: GraphQLServerOptions
        request?: GraphQLServerRequest
        response?: GraphQLServerResponse
    }) => Record<string, unknown>
}

Available options

The GraphQLServer accepts the following GraphQLServerOptions. When calling the constructor or setOptions function, useful defaults from defaultGraphQLServerOptions are set and overwritten by the options provided in the constructor/function parameter.

GraphQL related options

• schema: The schema that is used to handle the request and send a response. If undefined the GraphQLServer will reject responses with a GraphQL error response with status code 500.
• shouldUpdateSchemaFunction: Function that can be used to determine whether a schema update should be executed.
• formatErrorFunction: Function that can be used to format occurring GraphQL errors. Given a GraphQLError it should return a GraphQLFormattedError. By default defaultFormatErrorFunction is called that uses error.toJSON to format the error.
• schemaValidationFunction: Function that is called when a schema is set or updated. Given a GraphQLSchema it can return a ReadonlyArray<GraphQLError> or an empty array if no errors occurred/should be returned. By default validateSchema from graphql-js library is called.
• parseFunction: Function that is called to create a DocumentNode with the extracted query in the request information. Given a source and ParseOptions it should return a DocumentNode. By default parse from graphql-js library is called.
• defaultValidationRules: Default validation rules that are used when validateSchemaFunction is called. Both defaultValidationRules and customValidationRules will be merged together when validateSchemaFunction is called. By default specifiedRules from graphql-js are used. Can be overwritten if no or other default rules should be used.
• customValidationRules: Custom validation rules that are used when validateSchemaFunction is called. Both defaultValidationRules and customValidationRules will be merged together when validateSchemaFunction is called. By default, an empty array is set. Can be overwritten to add additional rules like NoSchemaIntrospectionCustomRule.
• validationTypeInfo: Validation type info that is used when validateSchemaFunction is called.
• validationOptions: Validation options containing { maxErrors?: number } that is used when validateSchemaFunction is called.
• removeValidationRecommendations: If true removes validation recommendations like "users not found. Did you mean user?". For non-production environments it is usually safe to allow recommendations. For production environments when not providing access to third-party users it is considered good practice to remove these recommendations so users can not circumvent disabled introspection request by using recommendations to explore the schema.
• validateFunction: Validation function that validates the extracted request against the available schema. By default validate from graphql-js library is called.
• rootValue: Root value that is used when executeFunction is called. Can be used to define resolvers that handle how defined queries and/or mutations should be resolved (e.g. fetch object from database and return entity).
• fieldResolver: Field resolver function that is used when executeFunction is called. Default is undefined, if custom logic is necessary it can be added.
• typeResolver: Type resolver function that is used when executeFunction is called. Default is undefined, if custom logic is necessary it can be added.
• executeFunction: Execute function that executes the parsed DocumentNode (created in parseFunction) using given schema, values and resolvers. Returns a Promise or value of an ExecutionResult. By default execute from graphql-js library is called.
• extensionFunction: Extension function that can be used to add additional information to the extensions field of the response. Given a GraphQLRequestInfo, ExecutionResult, GraphQLServerOptions and context it should return undefined or an ObjMap of key-value-pairs that are added to theextensions field. By default defaultExtensions is used and returns undefined.
• reassignAggregateError: If true and the ExecutionResult created by the executeFunction contains an AggregateError (e.g. an error containing a comma-separated list of errors in the message and an originalError containing multiple errors) this function will reassign the originalError.errors to the ExecutionResult.errors field. This is helpful if another application creates AggregateErrors while the initiator of the request (e.g. a Frontend app) does not expect or know how to handle AggregateErrors.

Context function

• contextFunction: Given GraphQLServerOptions, GraphQLServerRequest and GraphQLServerResponse this function is used to create a context value of type Record<string, unknown> that is available in the whole request flow. Default implementation is defaultContextFunction that returns an empty object. Can be used to extract information from the request and/or response and return them as context. This is often used to extract headers like 'Authorization' and set them in the execute function.

Error messages

• executionResultErrorMessage:: Error message that is used in logging if a response contains an errors element.
• fetchErrorMessage:: If provided and not set to undefined, used as fixed error message if a FetchError occurs.
• graphqlExecutionErrorMessage:: Error message that is used in logging if an error is thrown when execute function is called.
• validationErrorMessage:: Error message that is used in logging if one or more errors occurred when calling the validate function.

Error responses

• methodNotAllowedResponse:: Function given a method as string returns an error that the used method is not allowed by GraphQLServer.
• invalidSchemaResponse:: Default error that is returned with set schema is invalid.
• missingQueryParameterResponse:: Default error that is returned if no query is available in the GraphQLRequestInfo.
• onlyQueryInGetRequestsResponse:: Function given an operation as string returns an error that the used operation is not allowed for GET requests.

Metrics options

• collectErrorMetricsFunction:: Given an error name as string, error as unknown, GraphQLServerOptions and context as Record<string, unknown>, this function can be used to trigger collecting error metrics. Default implementation is defaultCollectErrorMetrics which increases the error counter for the given errorName or Error by 1.

Response Validation options

• responseStandardSchema:: StandardSchemaV1 to validate response against. By default noOpStandardSchema is used and returns the value and no issues.

Technical components and options

• logger: Logger to be used in the GraphQL server. TextLogger and JsonLogger as well as NoStacktraceTextLogger and NoStacktraceJsonLogger (useful for tests without the need for a stacktrace) are available in the module. Own Logger can be created by implementing Logger interface. Note: NoLogger (useful if no logging should be done but logger is required) is available in package @dreamit/graphql-testing.
• extractInformationFromRequest: Async function that can be used to extract information from the GraphQLServerRequest and return a Promise<GraphQLRequestInfo>. By default, the extractInformationFromRequest function is used that tries to extract the information from the body (using request.body field or request.text() function) and URL params of the request.
• sendResponse: Function used to send a fitting response being either a data or error response. By default, the sendResponse is used that tries to create and send a response using the functions provided by the given GraphQLServerResponse.
• metricsClient: The MetricsClient used to collect metrics from the GraphQLServer. By default, the SimpleMetricsClient is used that collects three custom metrics. Own MetricsClient can be used by implementing MetricsClient interface.
• responseEndChunkFunction: Function used to adjust the chunk/body before it is used in the response.end or response.send function call in the sendResponse function. By default it stringifies the ExecutionResult.
• adjustGraphQLExecutionResult: Function used to adjust the GraphQLExecutionResult before it is returned.
• returnNotAcceptableForUnsupportedResponseFormat: Boolean value that when set to true returns a response with status code "406 Not Acceptable" if the client does not provide an accept request header or the values in the header do not contain either "application/graphql-response+json" or "application/json". Default: false

Customize and extend GraphQLServer

To make it easier to customize and extend the GraphQLServer classes and class functions are public. This makes extending a class and overwriting logic easy.

In the example below the logic of TextLogger is changed to add the text "SECRETAPP" in front of every log output.

export class SecretApplicationTextLogger extends TextLogger {
    prepareLogOutput(logEntry: LogEntry): string {
        return `SECRETAPP - ${super.prepareLogOutput(logEntry)}`
    }
}

Contact

If you have problems, questions or issues please visit our Issue page and open a new issue if there are no fitting issues for your topic yet.

License

graphql-server is under MIT-License.