What is the difference between onOperation and onSubscribe hooks ?

[97amarnathk]

Hey, I was going through the graphql-ws docs, and found that here we have 2 different hooks:

• onOperation
• onSubscribe

My understanding is that when I make a new graphql subscription, the hooks are executed in the following order:

• onConnect
• onOperation
• onSubscribe
• for each payload sent from server to client:
  • onNext

Am I missing anything out in this ?

So if this is the order, then in the custom authentication example, why is the auth being done in onSubscribe? Shouldnt it be done in onOperation ?

I previously used subscriptions-transport-ws and over there we did authentication inside onOperation. I am assuming that graphql-ws and subscription-transport-ws have the use for onOperation

[enisdenjo]

You might be mixing "subscribe" with GraphQL subscriptions, but that is not the case. The client "subscribes" for events on the server, onSubscribe is the first to be called. It allows you to manipulate the the execution arguments and skip the built-in validation and exec args construction. With it you can use dynamic schemas, implement persisted queries, skip validation, apply custom auth or introduce completely custom subscription behaviour (check the recipes out). Check it out here:

graphql-ws/src/server.ts

Lines 619 to 654 in f24e9ba

	let execArgs: ExecutionArgs;
	const maybeExecArgsOrErrors = await onSubscribe?.(ctx, message);
	if (maybeExecArgsOrErrors) {
	if (areGraphQLErrors(maybeExecArgsOrErrors))
	return await emit.error(maybeExecArgsOrErrors);
	else if (Array.isArray(maybeExecArgsOrErrors))
	throw new Error(
	'Invalid return value from onSubscribe hook, expected an array of GraphQLError objects',
	);
	// not errors, is exec args
	execArgs = maybeExecArgsOrErrors;
	} else {
	// you either provide a schema dynamically through
	// `onSubscribe` or you set one up during the server setup
	if (!schema)
	throw new Error('The GraphQL schema is not provided');
	const args = {
	operationName: payload.operationName,
	document: parse(payload.query),
	variableValues: payload.variables,
	};
	execArgs = {
	...args,
	schema:
	typeof schema === 'function'
	? await schema(ctx, message, args)
	: schema,
	};
	const validationErrors = (validate ?? graphqlValidate)(
	execArgs.schema,
	execArgs.document,
	);
	if (validationErrors.length > 0)
	return await emit.error(validationErrors);
	}

onOperation, on the other hand, gets called immediately after the operation (query, mutation or subscription) is performed by GraphQL. It allows you to manipulate the execution results. Check it out here:

graphql-ws/src/server.ts

Lines 676 to 690 in f24e9ba

	// the execution arguments have been prepared
	// perform the operation and act accordingly
	let operationResult;
	if (operationAST.operation === 'subscription')
	operationResult = await (subscribe ?? graphqlSubscribe)(execArgs);
	// operation === 'query' || 'mutation'
	else operationResult = await (execute ?? graphqlExecute)(execArgs);
	const maybeResult = await onOperation?.(
	ctx,
	message,
	execArgs,
	operationResult,
	);
	if (maybeResult) operationResult = maybeResult;

[enisdenjo]

The complete order of callbacks is then:

1. onConnect
2. onSubscribe
3. onOperation
4. onNext
5. onError or onComplete
6. onDisconnect
7. onClose

[97amarnathk]

Okay. this is helpful. Thanks! 👍🏽