@axinom/mosaic-graphql-common 0.1.0-rc.0

package/src/postgraphile/postgraphile-options-builder.ts

@@ -0,0 +1,510 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import PgPubsub from '@graphile/pg-pubsub';
+import { Request, Response } from 'express';
+import { NodePlugin, Plugin } from 'graphile-build';
+import { GraphQLError } from 'graphql';
+import { IncomingMessage } from 'http';
+import {
+  GraphQLErrorExtended,
+  Middleware,
+  Options,
+  PostGraphileOptions,
+  PostGraphilePlugin,
+  makePluginHook,
+  mixed,
+} from 'postgraphile';
+import { Dict } from '../common';
+import { enhanceGraphqlErrors } from './enhance-graphql-errors';
+
+/**
+ * This is the function type that must be used when developing Hook Plugin factory functions.
+ * 
+ * @example
+ * ```ts
+    const subscriptionAuthorizationHookFactory = (
+      buildOptions: PostGraphileOptions<Request, Response> | undefined,
+    ): PostGraphilePlugin => {
+      return {
+        // returns a PostGraphilePlugin
+      }
+    }
+ * ```
+ */
+export type HookPluginFactory = (
+  buildOptions: PostGraphileOptions<Request, Response> | undefined,
+) => PostGraphilePlugin;
+
+/**
+ * A builder class that allows construction of postgraphile options using multiple dedicated extension methods.
+ */
+export class PostgraphileOptionsBuilder {
+  private transformers: ((
+    options: PostGraphileOptions<Request, Response>,
+  ) => PostGraphileOptions<Request, Response>)[] = [];
+
+  private headers: Dict<number | string | string[]> = {};
+  private pluginHooks: Set<PostGraphilePlugin> = new Set<PostGraphilePlugin>();
+  private hookFuncs: Set<HookPluginFactory> = new Set<HookPluginFactory>();
+
+  /**
+   * Builds a postgraphile options object with previously used extension methods.
+   */
+  public build(): PostGraphileOptions<Request, Response> {
+    let options: PostGraphileOptions<Request, Response> = {};
+    for (const transform of this.transformers) {
+      options = transform(options);
+    }
+
+    this.buildHeadersHookPlugin();
+
+    // Build plugin hooks from hook functions
+    [...this.hookFuncs].map((hookFunc) => {
+      this.pluginHooks.add(hookFunc(options));
+    });
+
+    if (this.pluginHooks.size > 0) {
+      options.pluginHook = makePluginHook([...this.pluginHooks]);
+    }
+
+    return options;
+  }
+
+  /**
+   * Builds a hook plugin that adds custom headers to http responses.
+   */
+  private buildHeadersHookPlugin(): void {
+    if (Object.keys(this.headers).length > 0) {
+      this.pluginHooks.add({
+        'postgraphile:http:handler': (
+          req: IncomingMessage,
+          { res }: { res: Response },
+        ) => {
+          for (const key in this.headers) {
+            if (Object.prototype.hasOwnProperty.call(this.headers, key)) {
+              res.setHeader(key, this.headers[key]);
+            }
+          }
+          return req;
+        },
+      });
+    }
+  }
+
+  /**
+   * This builder option must be used if the Hook Plugin requires PostGraphileOptions in the logic.
+   * A function which returns a PostGraphilePlugin should be passed into this method.
+   * That function will use PostGraphileOptions created in the build() method and attach the plugin returned from the function as a Postgraphile Hook.
+   * @example    
+   * 
+   * ```ts
+     new PostgraphileOptionsBuilder()
+      .addHookPluginFactory(customHookFactory)
+   * ```
+   *
+   * @param hookFunction This is a function which takes an argument of type PostGraphileOptions<Request, Response> and returns a PostGraphilePlugin object.
+   * @returns
+   */
+  public addHookPluginFactory(
+    hookFunction: HookPluginFactory,
+  ): PostgraphileOptionsBuilder {
+    this.hookFuncs.add(hookFunction);
+    return this;
+  }
+
+  /**
+   * This function takes a PostGraphilePlugin object and attaches it as a Postgraphile Hook when build() is called.
+   * @example   
+   * 
+   * ```ts
+     new PostgraphileOptionsBuilder()
+      .addHookPluginFunction(subscriptionAuthorizationHook)
+   * ```
+   *
+   * @param hookPlugin This is a PostGraphilePlugin object.
+   * @returns
+   */
+  public addHookPlugin(
+    hookPlugin: PostGraphilePlugin,
+  ): PostgraphileOptionsBuilder {
+    this.pluginHooks.add(hookPlugin);
+    return this;
+  }
+
+  /**
+   * Sets `pgSettings` property of postgraphile options object. 
+   * Example:    
+   * 
+   * ```ts
+     new PostgraphileOptionsBuilder()
+      .setPgSettings(async req => {
+        const { subject } = await getManagementAuthenticationContext(req, idServiceParams);
+        return buildPgSettings(subject, config.dbGqlRole, config.serviceId);
+      })
+   * ```
+   *
+   * @param pgSettings A plain object specifying custom config values to set in the PostgreSQL transaction (accessed via current_setting('my.custom.setting')) or an (optionally asynchronous) function which will return the same (or a Promise to the same) based on the incoming web request (e.g. to extract session data).
+   */
+  public setPgSettings(
+    pgSettings: (req: Request) => Promise<Dict<mixed>> | Dict<mixed>,
+  ): PostgraphileOptionsBuilder {
+    this.transformers.push((options) => {
+      options.pgSettings = pgSettings;
+      return options;
+    });
+    return this;
+  }
+
+  /**
+   * Sets `handleErrors` property of postgraphile options object. 
+   * Example:    
+   * 
+   * ```ts
+     new PostgraphileOptionsBuilder()
+      .setErrorsHandler((errors, req) => {
+        return enhanceGraphqlErrors(
+          result.errors,
+          req.body.operationName,
+          customizeGraphQlErrorFields(defaultPgErrorMapper),
+          logGraphQlError(defaultWriteLogMapper, this.logger),
+        );
+      }
+    })
+   * ```
+   *
+   * @param handleErrors Enables ability to modify errors before sending them down to the client. Optionally can send down custom responses. If you use this then showErrorStack and extendedError may have no effect.
+   */
+  public setErrorsHandler(
+    handleErrors: (
+      errors: readonly GraphQLError[],
+      req: Request,
+      res: Response,
+    ) => GraphQLErrorExtended[],
+  ): PostgraphileOptionsBuilder {
+    this.transformers.push((options) => {
+      options.handleErrors = handleErrors;
+      return options;
+    });
+    return this;
+  }
+
+  /**
+   * Sets properties of postgraphile options object to be used in without any conditions. Additional calls will override and add properties.
+   * Example:    
+   * 
+   * ```ts
+     new PostgraphileOptionsBuilder()
+      .setProperties({
+        enableCors: true,
+        dynamicJson: true,
+        ignoreRBAC: false,
+        legacyRelations: 'omit',
+        setofFunctionsContainNulls: false,
+      })
+   * ```
+   * @param properties An object containing postgraphile options.
+   */
+  public setProperties(
+    properties: PostGraphileOptions<Request, Response>,
+  ): PostgraphileOptionsBuilder {
+    this.transformers.push((options) => {
+      return { ...options, ...properties };
+    });
+    return this;
+  }
+
+  /**
+   * Sets properties of postgraphile options object to be used based on some
+   * condition (use if true, omit if false). Additional calls will override and
+   * add properties. 
+   * Example:    
+   * 
+   * ```ts
+     new PostgraphileOptionsBuilder()
+      .setConditionalProperties(config.isDev, {
+        exportGqlSchemaPath: './src/generated/schema.graphql',
+        watchPg: true,
+        graphiql: true,
+        enhanceGraphiql: true,
+        allowExplain: true,
+      })
+   * ```
+   * @param properties An object containing postgraphile options.
+   */
+  public setConditionalProperties(
+    condition: boolean,
+    properties: PostGraphileOptions<Request, Response>,
+  ): PostgraphileOptionsBuilder {
+    if (condition) {
+      this.transformers.push((options) => {
+        return { ...options, ...properties };
+      });
+    }
+    return this;
+  }
+
+  /**
+   * Sets all necessary postgraphile properties to enable subscriptions. 
+   * Example:
+   * 
+   * ```ts
+     new PostgraphileOptionsBuilder()
+      .enableSubscriptions({ 
+        plugin: SubscriptionsPlugin, 
+        websocketMiddlewares: middlewares, 
+        hookFactory: subscriptionAuthorizationHookFactory
+      })
+   * ```
+   * 
+   * Results in something like this:
+   * 
+   * ```ts
+      import PgPubsub from '@graphile/pg-pubsub';
+      import { makePluginHook } from 'postgraphile';
+      //.........    
+      {
+          appendPlugins: [SubscriptionsPlugin], // Other plugins will be included if they were added using other methods
+          pluginHook: makePluginHook([PgPubsub, subscriptionAuthorizationHook]),
+          subscriptions: true,
+          websocketMiddlewares, // Empty array if websocketMiddlewares are not specified
+      }
+   * ```
+   *
+   * To make sure that Postgraphile is able to correctly establish WebSockets
+   * connection, additional changes should be done by using
+   * `enhanceHttpServerWithSubscriptions`. 
+   * 
+   * See more here: https://www.graphile.org/postgraphile/subscriptions/#advanced-setup
+   *
+   * @param plugin Graphile engine plugin that adds one or multiple subscription
+   * endpoints. Can be added separately. 
+   * @param websocketMiddlewares If you're using websockets (subscriptions ||
+   * live) then you may want to authenticate your users using sessions or
+   * similar. You can pass some simple middlewares here that will be executed
+   * against the websocket connection in order to perform authentication. 
+   * @param hookFactory A factory function for a Postgraphile hook plugin.
+   */
+  public enableSubscriptions({
+    plugin,
+    websocketMiddlewares,
+    hookFactory,
+  }: {
+    plugin: Plugin;
+    websocketMiddlewares?: Middleware<Request, Response>[];
+    hookFactory?: HookPluginFactory;
+  }): PostgraphileOptionsBuilder {
+    this.transformers.push((options) => {
+      options.subscriptions = true;
+      options.appendPlugins = [
+        ...new Set<Plugin>([...(options.appendPlugins ?? []), plugin]),
+      ];
+
+      // Add the pub/sub realtime provider
+      // This is for PostGraphile server plugins: https://www.graphile.org/postgraphile/plugins/
+      this.pluginHooks.add(PgPubsub);
+
+      if (websocketMiddlewares) {
+        options.websocketMiddlewares = [
+          ...new Set<Middleware<Request, Response>>([
+            ...(options.websocketMiddlewares ?? []),
+            ...websocketMiddlewares,
+          ]),
+        ];
+      } else if (!options.websocketMiddlewares) {
+        options.websocketMiddlewares = [];
+      }
+
+      if (hookFactory) {
+        this.hookFuncs.add(hookFactory);
+      }
+      return options;
+    });
+    return this;
+  }
+
+  /**
+   * Adds multiple graphile engine plugins to `appendPlugins` array of postgraphile options object. `setAdditionalGraphQLContextFromRequest` and `addGraphileBuildOptions` methods can be used to pass parameters to said plugins.
+   * Example: 
+   * 
+     ```ts
+     new PostgraphileOptionsBuilder()
+      .addPlugins(
+        PgSimplifyInflectorPlugin,
+        ScalarTypesPlugin,
+        SmartTagsPlugin,
+        ValidationDirectivesPlugin,
+      )
+     ```
+   * @param plugins Comma-separated list of Graphile Engine schema plugins to load after the default plugins.
+   */
+  public addPlugins(...plugins: Plugin[]): PostgraphileOptionsBuilder {
+    this.transformers.push((options) => {
+      options.appendPlugins = [
+        ...new Set<Plugin>([...(options.appendPlugins ?? []), ...plugins]),
+      ];
+      return options;
+    });
+    return this;
+  }
+
+  /**
+   * Adds multiple graphile engine plugins to `appendPlugins` array of postgraphile options object. 
+   * `setAdditionalGraphQLContextFromRequest` and `addGraphileBuildOptions` methods can be used to pass parameters to said plugins.
+   * Explicit condition parameter is used to make a decision if plugins should be used or not (use if true, omit if false). 
+   * Example: 
+   * 
+     ```ts
+     new PostgraphileOptionsBuilder()
+      .addConditionalPlugins(config.isDev || config.enablePopulatePlugins, PopulateMoviesPlugin, PopulateTvshowsPlugin)
+     ```
+   * @param plugins Comma-separated list of Graphile Engine schema plugins to load after the default plugins.
+   */
+  public addConditionalPlugins(
+    condition: boolean,
+    ...plugins: Plugin[]
+  ): PostgraphileOptionsBuilder {
+    if (condition) {
+      this.addPlugins(...plugins);
+    }
+    return this;
+  }
+
+  /**
+   * Skips multiple default postgraphile plugins by adding them to `skipPlugins` array of postgraphile options object . 
+   * Example: 
+   * 
+     ```ts
+     new PostgraphileOptionsBuilder()
+      .skipPlugins(NodePlugin, MutationPayloadQueryPlugin)
+     ```
+   * @param plugins Comma-separated list of Graphile Engine schema plugins to skip.
+   */
+  public skipPlugins(...plugins: Plugin[]): PostgraphileOptionsBuilder {
+    this.transformers.push((options) => {
+      options.skipPlugins = [
+        ...new Set<Plugin>([...(options.skipPlugins ?? []), ...plugins]),
+      ];
+      return options;
+    });
+    return this;
+  }
+
+  /**
+   * Adds properties to resulting `graphileBuildOptions` property of postgraphile options object. Useful for modifying default postgraphile plugin settings.
+   * Example:
+   * 
+     ```ts
+     new PostgraphileOptionsBuilder()
+      .addGraphileBuildOptions({ pgSkipInstallingWatchFixtures: true })
+     ```
+   * @param graphileBuildOptions Additional Options to pass through into the graphile schema building system (received via the second argument of a plugin).
+   */
+  public addGraphileBuildOptions(
+    graphileBuildOptions: Partial<Options>,
+  ): PostgraphileOptionsBuilder {
+    this.transformers.push((options) => {
+      options.graphileBuildOptions = {
+        ...(options.graphileBuildOptions ?? {}),
+        ...graphileBuildOptions,
+      };
+      return options;
+    });
+    return this;
+  }
+
+  /**
+   * Adds `additionalGraphQLContextFromRequest` property to postgraphile options object. Define only once. Multiple calls will not expand previous calls, but will override them.
+   * 
+   * Example: 
+     ```ts
+     new PostgraphileOptionsBuilder()
+      .setAdditionalGraphQLContextFromRequest(async req => {
+        const { subject } = await getManagementAuthenticationContext(req);
+        return { subject, serviceId: config.serviceId };
+      })
+     ```
+   * @param callback Some Graphile Engine schema plugins may need additional information available on the context argument to the resolver - you can use this function to provide such information based on the incoming request - you can even use this to change the response , e.g. setting cookies. 
+   */
+  public setAdditionalGraphQLContextFromRequest(
+    callback: (req: Request, res: Response) => Promise<Record<string, any>>,
+  ): PostgraphileOptionsBuilder {
+    this.transformers.push((options) => {
+      options.additionalGraphQLContextFromRequest = callback;
+      return options;
+    });
+    return this;
+  }
+
+  /**
+   * Enables or disables graphiql GUI depending on a passed condition parameter. Enable if true, disable if false.
+   * Sets 3 postgraphile properties: `graphiql`, `enhanceGraphiql` and `allowExplain`.
+   * Example:    
+   * 
+   * ```ts
+     new PostgraphileOptionsBuilder()
+      .setGraphiql(config.graphqlGuiEnabled)
+   * ```
+   */
+  public setGraphiql(condition: boolean): PostgraphileOptionsBuilder {
+    this.transformers.push((options) => {
+      return {
+        ...options,
+        ...{
+          graphiql: condition,
+          enhanceGraphiql: condition,
+          allowExplain: condition,
+        },
+      };
+    });
+    return this;
+  }
+
+  /**
+   * Sets a response header for each GraphQL request.
+   *
+   * @param name header name
+   * @param value header value
+   */
+  public setHeader(
+    name: string,
+    value: string | number | string[],
+  ): PostgraphileOptionsBuilder {
+    this.headers[name] = value;
+    return this;
+  }
+
+  /**
+   * Sets default values for properties that we see as best practices which most
+   * services should start from. This includes the default GraphQL errors handler,
+   * suggested default properties, development properties in dev-environments,
+   * and excludes the 'NodePlugin'.
+   */
+  public setDefaultSettings(
+    isDev: boolean,
+    graphqlGuiEnabled: boolean,
+  ): PostgraphileOptionsBuilder {
+    this.setErrorsHandler((errors) => {
+      return enhanceGraphqlErrors(errors);
+    })
+      .setProperties({
+        enableCors: true,
+        dynamicJson: true,
+        ignoreRBAC: false,
+        legacyRelations: 'omit',
+        setofFunctionsContainNulls: false,
+
+        watchPg: false,
+        disableQueryLog: true,
+        retryOnInitFail: true,
+      })
+      .setConditionalProperties(isDev, {
+        exportGqlSchemaPath: './src/generated/graphql/schema.graphql',
+        watchPg: true,
+        disableQueryLog: false,
+        retryOnInitFail: false,
+      })
+      .setGraphiql(graphqlGuiEnabled)
+      // removes some nodeId and byNodeId endpoints, but still leaves support for cursor pagination
+      .skipPlugins(NodePlugin);
+    return this;
+  }
+}

package/src/postgraphile/websocket-utils.ts

@@ -0,0 +1,19 @@
+import { Request } from 'express';
+import { WebSocket } from 'graphql-ws';
+
+/**
+ * Extract the reference to web socket when given a request object that is coming
+ * from Postgraphile. The web socket reference is attached as a symbol.
+ *
+ * @param req A Postgraphile request.
+ * @returns
+ */
+export const getWebsocketFromRequest = (
+  req: Request,
+): WebSocket | undefined => {
+  const websocketSymbol = Object.getOwnPropertySymbols(req.socket).filter(
+    (sym) => sym.description === 'websocket',
+  )[0];
+  const websocket = (req as any).socket[websocketSymbol];
+  return websocket as WebSocket;
+};