feat(client): specify headers for individual subscribe calls

[RMHonor]

This allows each subscribe call on the client to specify request headers, useful if your requests need to send different headers depending on the operation.

It will merge the headers with any specified on the client, overriding any duplicates.

Note: this only applies to distinct connection mode, as single connection won't be able to send new headers per oepration as there's only one request.

Example, pulling the Apollo context headers to match the HttpLink behaviour:

export class SSELink extends ApolloLink {
  private client: Client;

  constructor(options: ClientOptions) {
    super();
    this.client = createClient(options);
  }

  public request(operation: Operation): Observable<FetchResult> {
    return new Observable((sink) => {
      return this.client.subscribe<FetchResult>(
        { ...operation, query: print(operation.query) },
        {
          next: sink.next.bind(sink),
          complete: sink.complete.bind(sink),
          error: sink.error.bind(sink),
        },
        undefined,
        operation.getContext().headers,
      );
    });
  }
}

[enisdenjo]

Thanks for this! Certnaily something we could improve.

By convention, I do things the other way around - instead of adding an extra argument to the subscribe and thus fixing the 3rd argument to always be headers (where you could potentially want to change other things, like the url or retry behaviour or any other related config option); I'd rather add an extra argument to headers instead which accepts the RequestParams and changes headers accordingly.

Not only would you remove the lock on the subscribe method; but, since there's a high chance multiple subscribes will need to change headers, you would also centralise the headers manipulation (instead of changing multiple subscribes you would change one headers).

What do you think?

[RMHonor]

That was my first instinct as well, but the RequestParams type purely contains GQL information, and by exposing this on the subscribe call, it allows any sort of manipulation at the point of request. In my example case it allows us access to the Apollo client context so we can match the HttpLink behvaiour.

However I recognise that we probably shouldn't be designing an API around alternative systems or specific use cases.

An alternative idea, could the requestParams take arbitrary data (a bit like extensions but not sent on the network), which would then be accessible in the headers callback? I think this follows patterns I've seen elsewhere.

// extend the request params type
interface RequestParams<T = any> {
  operationName?: string;
  query: string;
  variables?: Record<string, unknown>;
  extensions?: Record<string, unknown>;
  extra?: T;
}

// extra accessible from headers
const client = createClient({
  uri: "https://theguild.com/graphql",
  headers: (requestParams) => ({
    "x-my-header": requestParams.extra,
  }),
});

// call subscribe with arbitrary params
client.subscribe<ExecutionResult>(
  { ...operation, query: print(operation.query), extra: "foo" },
  {
   next: sink.next.bind(sink),
   complete: sink.complete.bind(sink),
   error: sink.error.bind(sink),
 },
  undefined,
  operation.getContext().headers,
);