@tinkerstack/graphql-annotation 0.0.0

package/src/example/producer/producer.example.ts

@@ -0,0 +1,28 @@
+import { Module } from "@nestjs/common";
+import { Query, Resolver } from "@nestjs/graphql";
+import { InjectableArg, ProtectedResolver } from "../consumer/consumer.example";
+
+@Resolver()
+export class ExampleProducerResolver {
+  @Query(() => [String])
+  @ProtectedResolver(["admin"])
+  testProtectedQuery() {
+    return ["This resolver should only be available to if guard check passed"];
+  }
+  @Query(() => [String])
+  testQueryWithParam(
+    @InjectableArg("username", "session:username")
+    username: string
+  ) {
+    return [`Received params: ${username}`];
+  }
+  @Query(() => [String])
+  testPublicQuery() {
+    return ["This resolver should be available to everyone"];
+  }
+}
+
+@Module({
+  providers: [ExampleProducerResolver],
+})
+export class ExampleProducerModule {}

package/src/example/producer/producer.schema.gql

@@ -0,0 +1,20 @@
+# ------------------------------------------------------
+# THIS FILE WAS AUTOMATICALLY GENERATED (DO NOT MODIFY)
+# ------------------------------------------------------
+
+type GraphQLAnnotationMeta {
+  name: String!
+  resolvers: JSONObject!
+}
+
+"""
+The `JSONObject` scalar type represents JSON objects as specified by [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf).
+"""
+scalar JSONObject @specifiedBy(url: "http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf")
+
+type Query {
+  _annotations: GraphQLAnnotationMeta!
+  testProtectedQuery: [String!]!
+  testQueryWithParam(username: String!): [String!]!
+  testPublicQuery: [String!]!
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./modules";

package/src/modules/core/annotation.constants.ts

@@ -0,0 +1,37 @@
+export const ANNOTATION_METADATA = "graphql-annotation"; // Should not conflict
+export interface MethodInfo {
+  type: "method";
+  name: string;
+}
+export interface ParameterInfo {
+  type: "parameter";
+  paramIndex: number;
+  paramName: string;
+}
+export type AnnotationTarget = MethodInfo | ParameterInfo;
+export interface AnnotationInfo<T = unknown> {
+  annotation: string;
+  target: AnnotationTarget;
+  data: T;
+}
+
+export const ANNOTATION_RESOLVER_METADATA = "graphql-annotation-resolver";
+export interface AnnotationResolverMetadata {
+  annotation: string;
+}
+
+type SourceName = string;
+type RemoteURL = string;
+export type AnnotationSchemaSources = Record<SourceName, RemoteURL>;
+
+export type ResolverName = string;
+export type GraphQLResolversAnnotations = Record<
+  ResolverName,
+  AnnotationInfo[]
+>;
+
+export const GRAPHQL_ANNOTATION_RESOLVER_METADATA =
+  "graphql-annotation-provider";
+export type GraphQLAnnotationResolverMetadata = {
+  name: string;
+};

package/src/modules/core/annotation.decorators.ts

@@ -0,0 +1,147 @@
+import { SetMetadata } from "@nestjs/common";
+import { Args } from "@nestjs/graphql";
+import "reflect-metadata";
+import {
+  ANNOTATION_METADATA,
+  ANNOTATION_RESOLVER_METADATA,
+  AnnotationInfo,
+  AnnotationResolverMetadata,
+} from "./annotation.constants";
+
+/**
+ * Applies an annotation to a Query or Mutation handler or parameter for
+ * external stitching party to interpret.
+ *
+ * For parameter decorator, you must specify `parameter` option for external providers.
+ *
+ * @publicApi
+ */
+export function Annotate(
+  name: string,
+  opts?: { data?: Record<string, any>; parameter?: undefined },
+): MethodDecorator;
+/**
+ * Applies an annotation to a Query or Mutation handler or parameter for
+ * external stitching party to interpret.
+ *
+ * For parameter decorator, you must specify `parameter` option for external providers.
+ *
+ * @publicApi
+ */
+export function Annotate(
+  name: string,
+  opts: { data?: Record<string, any>; parameter: string },
+): ParameterDecorator & MethodDecorator;
+/**
+ * Applies an annotation to a Query or Mutation handler or parameter for
+ * external stitching party to interpret.
+ *
+ * For parameter decorator, you must specify `parameter` option for external providers.
+ *
+ * @publicApi
+ */
+export function Annotate(
+  name: string,
+  opts?: { data?: Record<string, any>; parameter?: string },
+): MethodDecorator & ParameterDecorator {
+  const annotationName = name;
+  const annotationData = opts?.data;
+
+  return (
+    target: Object,
+    propertyKey: string,
+    descriptorOrParameterIndex: number | TypedPropertyDescriptor<unknown>,
+  ) => {
+    switch (typeof descriptorOrParameterIndex) {
+      // Method
+      case "object": {
+        const descriptor = descriptorOrParameterIndex;
+        _updateAnnotation(descriptor.value ?? target, (meta) => ({
+          ...meta,
+          [annotationName]: {
+            annotation: annotationName,
+            data: annotationData,
+            target: {
+              type: "method",
+              name: propertyKey,
+            },
+          },
+        }));
+        break;
+      }
+      // Parameter
+      case "number": {
+        const paramIndex = descriptorOrParameterIndex;
+        const paramName = opts?.parameter;
+
+        if (!paramName)
+          throw new Error(
+            `Unable to apply annotation "${annotationName}". Parameter name not specified.`,
+          );
+
+        Args(paramName)(target, propertyKey, paramIndex);
+        _updateAnnotation(
+          target.constructor,
+          (meta) => ({
+            ...meta,
+            [`${annotationName}@${paramIndex}`]: {
+              annotation: annotationName,
+              data: annotationData,
+              target: {
+                type: "parameter",
+                paramIndex,
+                paramName,
+              },
+            },
+          }),
+          propertyKey,
+        );
+
+        break;
+      }
+      default:
+        throw new Error(
+          `Unable to attach annotation "${name}". Unsupported target.`,
+        );
+    }
+  };
+}
+type AnnotationList = Record<string, AnnotationInfo>;
+function _updateAnnotation(
+  target: any,
+  updateFn: (old: AnnotationList) => AnnotationList,
+  propertyKey?: string | symbol,
+) {
+  const meta = Reflect.getMetadata(ANNOTATION_METADATA, target) ?? {};
+
+  if (propertyKey)
+    Reflect.defineMetadata(
+      ANNOTATION_METADATA,
+      updateFn(meta),
+      target,
+      propertyKey,
+    );
+  else Reflect.defineMetadata(ANNOTATION_METADATA, updateFn(meta), target);
+}
+
+/**
+ * Declare `Resolver` method for resolving annotations
+ * @publicApi
+ */
+export function ResolveAnnotation(): MethodDecorator;
+/**
+ * Declare `Resolver` method for resolving annotations
+ * @publicApi
+ */
+export function ResolveAnnotation(annotation: string): MethodDecorator;
+/**
+ * Declare `Resolver` method for resolving annotations
+ * @publicApi
+ */
+export function ResolveAnnotation(name?: string): MethodDecorator {
+  return (target, property, descriptor) => {
+    SetMetadata(ANNOTATION_RESOLVER_METADATA, {
+      annotation: name ?? (property as string),
+    } satisfies AnnotationResolverMetadata)(target, property, descriptor);
+  };
+}

package/src/modules/core/annotation.loader.ts

@@ -0,0 +1,303 @@
+import { stitchSchemas } from "@graphql-tools/stitch";
+import { MapperKind, mapSchema } from "@graphql-tools/utils";
+import { FilterRootFields, wrapSchema } from "@graphql-tools/wrap";
+import { Injectable, Logger, ParamData } from "@nestjs/common";
+import {
+  ExternalContextCreator,
+  MetadataScanner,
+  ParamsFactory,
+} from "@nestjs/core";
+import { ParamMetadata } from "@nestjs/core/helpers/interfaces/params-metadata.interface";
+import {
+  GqlContextType,
+  GraphQLExecutionContext,
+  PARAM_ARGS_METADATA,
+} from "@nestjs/graphql";
+import { GqlParamtype } from "@nestjs/graphql/dist/enums/gql-paramtype.enum";
+import { GraphQLResolveInfo, GraphQLSchema } from "graphql";
+import { GraphQLClient } from "graphql-request";
+import {
+  ANNOTATION_RESOLVER_METADATA,
+  AnnotationResolverMetadata,
+  AnnotationSchemaSources,
+  ResolverName,
+} from "./annotation.constants";
+import {
+  GraphQLAnnotationMeta,
+  GraphQLAnnotationResolver,
+} from "./annotation.resolver";
+import {
+  isPlainObject,
+  loadGraphQLSchema,
+  shallowMerge,
+  split,
+} from "./annotation.utils";
+import { ResolverDiscoveryService } from "./resolver.explorer";
+import { instanceToPlain } from "class-transformer";
+
+@Injectable()
+export class GraphQLAnnotatedSchemaLoader {
+  private _logger = new Logger("GraphQLAnnotationModule");
+
+  constructor(
+    private readonly resolverDiscoveryService: ResolverDiscoveryService,
+    private readonly metadataScanner: MetadataScanner,
+    private readonly externalContextCreator: ExternalContextCreator,
+  ) {}
+
+  public async load(sources: AnnotationSchemaSources) {
+    const loadedSources = await this.batchLoadSources(sources);
+
+    const schema = stitchSchemas({
+      subschemas: loadedSources.map((s) => s.subschema),
+    });
+    const annotations = shallowMerge(
+      loadedSources.map((s) => s.annotation),
+    ) as GraphQLAnnotationMeta;
+    const annotationResolvers = await this.discoverAnnotationResolvers();
+
+    return this.embedAnnotationResolversToSchema(
+      schema,
+      annotations,
+      annotationResolvers,
+    );
+  }
+
+  private async discoverAnnotationResolvers() {
+    type AnnotationName = string;
+    type AnnotationCallback = (...args: any[]) => any;
+    const annotationResolvers = new Map<AnnotationName, AnnotationCallback>();
+
+    const paramFactory = new GraphQLAnnotationResolverParamsFactory();
+    const instances = this.resolverDiscoveryService.explore();
+
+    for (const { instance } of instances)
+      for (const methodName of this.metadataScanner.getAllMethodNames(
+        Object.getPrototypeOf(instance),
+      )) {
+        const resolverMeta = Reflect.getMetadata(
+          ANNOTATION_RESOLVER_METADATA,
+          instance[methodName],
+        ) as AnnotationResolverMetadata;
+
+        if (!resolverMeta) continue; // Skip non-annotated
+
+        this._logger.log(
+          `Discovered resolver for annotation "${resolverMeta.annotation}"`,
+        );
+        annotationResolvers.set(
+          resolverMeta.annotation,
+          this.externalContextCreator.create<
+            Record<number, ParamMetadata>,
+            GqlContextType
+          >(
+            instance,
+            instance[methodName],
+            methodName,
+            PARAM_ARGS_METADATA,
+            paramFactory,
+            undefined,
+            undefined,
+            undefined,
+            "graphql",
+          ),
+        );
+      }
+
+    return annotationResolvers;
+  }
+
+  private async batchLoadSources(sources: AnnotationSchemaSources) {
+    const pending = Object.entries(sources).map(async ([name, url]) => {
+      const loadId = `${name}@${url}`;
+      try {
+        const loaded = {
+          id: loadId,
+          url: url,
+          name: name,
+          subschema: await loadGraphQLSchema(url),
+          annotation: await this.loadAnnotations(url),
+        };
+
+        // Cleanup
+        // Remove `_annotations` from being merged to main schema
+        loaded.subschema.transforms = [
+          new FilterRootFields(
+            (op, fieldName) =>
+              !fieldName.endsWith(GraphQLAnnotationResolver.QUERY_NAME),
+          ),
+        ];
+
+        this._logger.log(`Loaded schema for ${loadId}`);
+        return loaded;
+      } catch (err) {
+        this._logger.error(`Unable to load schema for ${loadId}`);
+        throw err;
+      }
+    });
+
+    const [loaded, failed] = split(
+      await Promise.allSettled(pending),
+      (q) => q.status === "fulfilled",
+    );
+    if (failed.length > 0)
+      throw new Error(
+        `Failed to load ${failed.length} schema(s) from sources.`,
+      );
+
+    return loaded.map((l) => l.value);
+  }
+
+  private async loadAnnotations(url: string) {
+    const client = new GraphQLClient(url);
+
+    try {
+      type ExpectedResult = {
+        [GraphQLAnnotationResolver.QUERY_NAME]: GraphQLAnnotationMeta;
+      };
+      const res = await client.rawRequest<ExpectedResult>(`
+        query IntrospectAnnotations {
+          ${GraphQLAnnotationResolver.QUERY_NAME} {
+            name
+            resolvers
+          }
+        }
+      `);
+
+      this._logger.log(`Loaded annotations for ${url}`);
+      return res.data[GraphQLAnnotationResolver.QUERY_NAME];
+    } catch (err) {
+      this._logger.warn(`Failed to load annotations at ${url}, assuming empty`);
+      return {} as GraphQLAnnotationMeta;
+    }
+  }
+
+  private async embedAnnotationResolversToSchema(
+    schema: GraphQLSchema,
+    annotations: GraphQLAnnotationMeta,
+    annotationResolvers: Map<ResolverName, (...args: any[]) => any>,
+  ) {
+    return mapSchema(schema, {
+      [MapperKind.ROOT_FIELD]: (fieldSchema, name, type) => {
+        const fieldAnnotations = (annotations.resolvers[name] ?? [])
+          .map((info) => ({
+            ...info,
+            resolver: annotationResolvers.get(info.annotation)!, // NOTE: should be validated in filter
+          }))
+          .filter((info) => {
+            const annotationHasResolver = info.resolver !== undefined;
+            if (!annotationHasResolver)
+              this._logger.warn(
+                `Found unhandled annotation "${info.annotation}", skipping linking process`,
+              );
+
+            return annotationHasResolver;
+          });
+
+        if (fieldAnnotations.length <= 0) return fieldSchema; // No transform if there's no annotation
+
+        // If there exist a resolver for an annotate parameter, remove it from schema to prevent external injection
+        for (const annotation of fieldAnnotations)
+          if (annotation.target.type === "parameter" && fieldSchema.args)
+            delete fieldSchema.args[annotation.target.paramName];
+
+        const defaultResolver = fieldSchema.resolve!;
+        fieldSchema.resolve = async function (
+          parent,
+          args: Record<string, any>,
+          context: GraphQLExecutionContext,
+          info,
+        ) {
+          const annotationCallbacks = await Promise.all(
+            fieldAnnotations.map(async (annotation) => ({
+              annotation,
+              return: await annotation.resolver(
+                ...([
+                  info.rootValue,
+                  annotation.data as Record<string, unknown>,
+                  context,
+                  info,
+                ] satisfies GraphQLAnnotationResolverArgs),
+              ),
+            })),
+          );
+
+          const resolvedParams = annotationCallbacks.reduce(
+            (params, call) => {
+              if (call.annotation.target.type !== "parameter") return params;
+
+              const returnedClassType =
+                typeof call.return === "object" && !isPlainObject(call.return);
+              const returnValue = returnedClassType
+                ? instanceToPlain(call.return)
+                : call.return;
+              params[call.annotation.target.paramName] = returnValue;
+
+              return params;
+            },
+            {} as Record<string, any>,
+          );
+
+          return defaultResolver(
+            parent,
+            { ...args, ...resolvedParams },
+            context,
+            info,
+          );
+        };
+
+        return fieldSchema;
+      },
+    });
+  }
+}
+
+type GraphQLAnnotationResolverArgs = [
+  // Root/parent (follows graphql context to match)
+  any,
+  // Data
+  Record<string, unknown>,
+  // GraphQL Context
+  GraphQLExecutionContext,
+  // GraphQL Resolver Info
+  GraphQLResolveInfo,
+];
+class GraphQLAnnotationResolverParamsFactory implements ParamsFactory {
+  // This param factory extends graphql's own just with different inputs from annotations instead.
+  // https://github.com/nestjs/graphql/blob/master/packages/graphql/lib/factories/params.factory.ts#L9
+  exchangeKeyForValue(
+    type: number,
+    possibleKey: ParamData,
+    // NOTE: nestjs passes this in array, so we have to "get the first element"
+    argsContext: GraphQLAnnotationResolverArgs,
+  ) {
+    if (!argsContext) return null;
+    console.log(type, possibleKey, argsContext);
+
+    const args = {
+      parentValue: argsContext[0],
+      data: argsContext[1],
+      context: argsContext[2],
+      info: argsContext[3],
+    };
+
+    switch (type as GqlParamtype) {
+      case GqlParamtype.ROOT:
+        return args.parentValue;
+      case GqlParamtype.ARGS:
+        return possibleKey && args.data
+          ? args.data[possibleKey as string]
+          : args.data;
+      case GqlParamtype.CONTEXT:
+        return possibleKey && args.context
+          ? args.context[possibleKey as string]
+          : args.context;
+      case GqlParamtype.INFO:
+        return possibleKey && args.context
+          ? args.info[possibleKey as string]
+          : args.info;
+      default:
+        return null;
+    }
+  }
+}

package/src/modules/core/annotation.module.ts

@@ -0,0 +1,47 @@
+import { DynamicModule, Module } from "@nestjs/common";
+import { DiscoveryModule } from "@nestjs/core";
+import { GraphQLAnnotationResolver } from "./annotation.resolver";
+import { GraphQLAnnotatedSchemaLoader } from "./annotation.loader";
+import { ResolverDiscoveryService } from "./resolver.explorer";
+import {
+  ANNOTATION_RESOLVER_METADATA,
+  GraphQLAnnotationResolverMetadata,
+} from "./annotation.constants";
+
+@Module({})
+export class GraphQLAnnotationModule {
+  static forRoot(opts?: { serveAnnotations?: false }): DynamicModule;
+  static forRoot(opts: {
+    serveAnnotations: true;
+    serveConfig: GraphQLAnnotationResolverMetadata;
+  }): DynamicModule;
+  static forRoot(opts?: {
+    serveAnnotations?: boolean;
+    serveConfig?: GraphQLAnnotationResolverMetadata;
+  }): DynamicModule {
+    if (opts?.serveAnnotations)
+      return {
+        global: true,
+        module: GraphQLAnnotationModule,
+        imports: [DiscoveryModule],
+        providers: [
+          ResolverDiscoveryService,
+          GraphQLAnnotatedSchemaLoader,
+          {
+            provide: ANNOTATION_RESOLVER_METADATA,
+            useValue: opts.serveConfig!,
+          },
+          GraphQLAnnotationResolver,
+        ],
+        exports: [GraphQLAnnotatedSchemaLoader],
+      };
+
+    return {
+      global: true,
+      module: GraphQLAnnotationModule,
+      imports: [DiscoveryModule],
+      providers: [ResolverDiscoveryService, GraphQLAnnotatedSchemaLoader],
+      exports: [GraphQLAnnotatedSchemaLoader],
+    };
+  }
+}

package/src/modules/core/annotation.resolver.ts

@@ -0,0 +1,86 @@
+import { Inject, Injectable, Logger, OnModuleInit } from "@nestjs/common";
+import { MetadataScanner } from "@nestjs/core";
+import { Field, ObjectType, Query, Resolver } from "@nestjs/graphql";
+import { GraphQLJSONObject } from "graphql-scalars";
+import "reflect-metadata";
+import type {
+  AnnotationInfo,
+  GraphQLAnnotationResolverMetadata,
+  GraphQLResolversAnnotations,
+} from "./annotation.constants";
+import {
+  ANNOTATION_METADATA,
+  ANNOTATION_RESOLVER_METADATA,
+} from "./annotation.constants";
+import { ResolverDiscoveryService } from "./resolver.explorer";
+
+@ObjectType()
+export class GraphQLAnnotationMeta {
+  @Field(() => String)
+  name: string;
+
+  @Field(() => GraphQLJSONObject, { name: "resolvers" })
+  resolvers: GraphQLResolversAnnotations;
+}
+
+@Resolver()
+@Injectable()
+export class GraphQLAnnotationResolver implements OnModuleInit {
+  private _logger = new Logger("GraphQLAnnotationModule");
+
+  public static QUERY_NAME = "_annotations";
+  constructor(
+    private readonly metadataScanner: MetadataScanner,
+    private readonly resolverDiscoveryService: ResolverDiscoveryService,
+    @Inject(ANNOTATION_RESOLVER_METADATA)
+    private readonly meta: GraphQLAnnotationResolverMetadata,
+  ) {}
+
+  @Query(() => GraphQLAnnotationMeta, {
+    name: GraphQLAnnotationResolver.QUERY_NAME,
+  })
+  async getGraphQLAnnotations() {
+    return {
+      ...this.meta,
+      resolvers: this.resolverAnnotations,
+    } satisfies GraphQLAnnotationMeta;
+  }
+
+  private resolverAnnotations = {} as GraphQLResolversAnnotations;
+  async onModuleInit() {
+    this.resolverAnnotations = this.compileResolversAnnotations();
+  }
+
+  private compileResolversAnnotations() {
+    const instances = this.resolverDiscoveryService.explore();
+    const resolversAnnotations = {} as GraphQLResolversAnnotations;
+
+    for (const { instance } of instances)
+      for (const methodName of this.metadataScanner.getAllMethodNames(
+        Object.getPrototypeOf(instance),
+      )) {
+        const annotations = [
+          ...Object.values(
+            Reflect.getMetadata(ANNOTATION_METADATA, instance[methodName]) ??
+              {},
+          ),
+          ...Object.values(
+            Reflect.getMetadata(
+              ANNOTATION_METADATA,
+              instance.constructor,
+              methodName,
+            ) ?? {},
+          ),
+        ] as AnnotationInfo[];
+
+        if (annotations.length <= 0) continue;
+
+        resolversAnnotations[methodName] = annotations;
+        this._logger.log(
+          `Discovered annotated resolver "${instance.constructor.name}.${methodName}" with ${annotations.length} annotation(s)`,
+        );
+      }
+
+    return resolversAnnotations;
+  }
+}