@n1ru4l/graphql-public-schema-filter

This library allows filtering an existing GraphQL schema down into a subset of the original schema. It supports both the code first development flow of building GraphQL schemas (via GraphQL extension fields) and the SDL first development flow (via schema directives).

The implementation is smart and warns the user if the processed annotations would result in an invalid schema such as:

Object Type without fields
Field whose type is not part of the schema

If such a scenario is encountered the implementation will propagate and hide all fields/types that use types that are not marked as public or that would be invalid.

Why would you need this?

As I have been building GraphQL APIs I often had the need to have both a private and public API.

The private API is used for in-house products. Breaking changes can and will occur. It also includes types and fields specific to in-house application built around the API. The public API, however, is used by individuals not part of our organization. We cannot simply roll out breaking changes on the GraphQL API for those. Furthermore, they should only have access to a subset of the whole GraphQL graph. By generating a subgraph out of the internal graph we can hide stuff, without having to maintain and build two GraphQL schema.

Install instructions

This library requires graphql as a peer dependency and has a runtime dependency on @graphql-tools/utils.

yarn add -E @n1ru4l/graphql-public-schema-filter

Usage Instructions

This library is designed to be inclusive for anyone within the GraphQL.js ecosystem. It supports both the SDL makeExecutableSchema and code-first via extension fields flow.

There is no delegation or validation overhead when executing against the newly generated schema. It is highly recommended to built the public schema during server-startup and not on the fly during incoming requests.

Code-First

Annotate types and fields that should be public with the isPublic extension.

import { GraphQLObjectType, GraphQLString } from "graphql";
import { buildPublicSchema } from "@n1ru4l/graphql-public-schema-filter";

const GraphQLQueryType = new GraphQLObjectType({
  name: "Query",
  fields: {
    hello: {
      type: GraphQLString,
      resolve: () => "hi",
      extensions: {
        isPublic: true,
      },
    },
    secret: {
      type: GraphQLString,
      resolve: () => "sup",
    },
  },
});

const privateSchema = new GraphQLSchema({
  query: GraphQLQueryType,
});
const publicSchema = buildPublicSchema({ schema: privateSchema });
// serve privateSchema or publicSchema based on the request :)

You can also find this example within examples/src/schema.ts.

SDL-First

Instead of using the extension fields, we use the @public directive.

import { makeExecutableSchema } from "@graphql-tools/schema";
import {
  publicDirectiveSDL,
  buildPublicSchema,
} from "@n1ru4l/graphql-public-schema-filter";

const source = /* GraphQL */ `
  type Query {
    hello: String @public
    secret: String
  }
`;

const privateSchema = makeExecutableSchema({
  typeDefs: [publicDirectiveSDL, source],
});
const publicSchema = buildPublicSchema({ schema: privateSchema });
// serve privateSchema or publicSchema based on the request :)

FAQ

Why `isPublic` and `@public` over `isPrivate` and `@private`?

Deny-listing is more prone to errors than allow-listing. By adding a directive/extension field we explicitly set something to public. The other way around it is easier to forgot to add a @private/ isPrivate annotation, which would automatically result in the new fields being public. Being verbose about what fields are public is the safest way.

Why is the no more granular control that allows building multiple unique public schemas?

I considered this at the beginning, but in practice we never had a use for this. Having multiple public schemas requires maintaining a lot of documentation. In our use-case we only have a public and a private schema. There is still role based access for the public schema. certain users are not allowed to select specific fields. Instead of hiding those fields for those users we instead deny operations that select fields the users are not allowed to select before even executing it with the envelop useOperationFieldPermissions plugin.

You can overwrite the isPublic function which is used to determine whether a field or type is public based on directives and extensions. This allows to fully customize the behavior based on your needs.

type SharedExtensionAndDirectiveInformation = {
  extensions?: Maybe<{
    [attributeName: string]: any;
  }>;
  astNode?: Maybe<
    Readonly<{
      directives?: ReadonlyArray<DirectiveNode>;
    }>
  >;
};

export const defaultIsPublic = (
  input: SharedExtensionAndDirectiveInformation
): boolean =>
  input.extensions?.["isPublic"] === true ||
  !!input.astNode?.directives?.find(
    (directive) => directive.name.value === "public"
  );

License

MIT

Customizing `isPublic` bahaviour doesn't always take effect.

I'm trying to reverse the bahaviour of the library. Instead of allow-listing, I want to implement deny-listing. I've read the README. I know it's not the ideal solution. But there's a restriction in our current setup that is forcing us to do deny-listing. At least for now.

So I started out by creating the type definitons for my new direction @undocumented:

directive @undocumented on OBJECT | FIELD_DEFINITION | ENUM | UNION | INTERFACE | INPUT_OBJECT | SCALAR | INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION

Then I customized the isPublic method to look for the existance of @undocumented instead of the default @public directive:

  return buildPublicSchema({
    schema: baseSchema,
    isPublic: (input: SharedExtensionAndDirectiveInformation): boolean => {
      const isPublic = !input.astNode?.directives
        ?.map((directive) => directive.name.value)
        .includes('undocumented');

      return isPublic;
    }
  });

And then I tried to annotate a type and a field defenition with @undocumented:

  type Lolo @undocumented {
    name: String
    dodo: Boolean
  }

  type Query {
    _empty: String @undocumented
  }

Expected behaviour: neither Query._empty nor Lolo should be returned in the introspection schema.

Actual behaviour: Both fields are returned in the introspection schema.

If I remove my customization and use @public, the library is working as expected.

n1ru4l / graphql-public-schema-filter Goto Github PK

graphql-public-schema-filter's Introduction

@n1ru4l/graphql-public-schema-filter

Why would you need this?

Install instructions

Usage Instructions

Code-First

SDL-First

FAQ

Why isPublic and @public over isPrivate and @private?

Why is the no more granular control that allows building multiple unique public schemas?

License

graphql-public-schema-filter's People

Contributors

Stargazers

Watchers

Forkers

graphql-public-schema-filter's Issues

Edited/Blocked

Open

Ignored or Blocked

Detected dependencies

Recommend Projects

Recommend Topics

Recommend Org

Why `isPublic` and `@public` over `isPrivate` and `@private`?