Compiled Experience

Adding cross cutting concerns to a GraphQL service

Wed, 22 Sep 2021 00:00:00 +0000

What are cross cutting concerns?

Typically within a system we can consider something a cross cutting concern if it has to be involved with every action (in this case a request), these things tend to be security, logging, validation and more.

Using middleware

The idea of a pipeline of middleware that serves every request makes the process of adding some cross cutting concerns to our GraphQL service really quite easy. The Hot Chocolate framework allows you to add “request middleware” that runs for every request, or “field middleware” that runs on every field within that that request. We may use the “request middleware” to ensure basis metrics such as operation name and timings are sent to our observablity system to allow for easier diagbosis of problems. We may use “field middleware” to ensure every argument on a field is correctly validated”. Both of these are done at the service setup.

services.AddGraphQLServer()
    .UseRequest<LoggingMiddleware>() // Adds middleware to every request
    .UseField<ValidationMIddleware>() // Adds middleware to every field in the request

One problem with field middleware is that it’s a pretty big hammer, we’re essentially adding a little bit of code to the resolution of every single field in our schema. For some concerns this may be fine, the scenario we wish to cover is required on 90% of the fields in our schema. However sometimes this may feel unwarranted, we want to add field middleware to a smaller subset of our fields and not go with a blanket approach.

We can target specific fields a few different ways depending on how we’re setting up our schema, if we’re using a “code first approch” it would look something like the following, here we’re being very targeted, applying the middleware to only the fielsd we care about.

public void Configure(IObjectTypeDescriptor descriptor)
{
    descriptor.Field("productSearch")
        .Use<ValidationMIddleware>()
}       // reset of field definition here

If you’re using a schema first approach it’s a bit more complicated, typically the approach I’ve used before is to declare a directive, attach the middleware to the directive and then apply the directive on the schema where I want the middleware. In fact if you’ve used the @authorize directive from Hot Chocolate, this is exactly what is happening, we’re using the directive to apply a piece of middleware to the field that will enforce security.

There are some risks with this approach though, we’re relying on the developer to remember every place we should be putting the middleware as they add new types and fields to our schema, there is a reasonable chance that the middleware would be forgotten. For a cross cutting concern such as security we could have an unsecured field or other incidents.

Creating a pit of success

As a senior developer I really like thinking about problems and how to make them easier for others on the team. The phrase “pit of success” is a way to describe this, we want to make the easy, secure, performant approach the easiest to implement, if the easiest path is the best path then we’ll “fall” into the correct approach. For our current problem, is there way we can specifically target our middleware without applying it everywhere but not rely on a developer remembering to add it. We can do this with a TypeInterceptor, this is a class that we use at schema creation to inject cross cutting concerns in an automatic manner.

The class allows us to inject behavior at different times, for this scenario we want to do it just before the type is completed. We first check to see if we’re working with a object type, from there we check each field, if it as any arguments we add our validation middleware.

public class ValidationTypeInterceptor : TypeInterceptor
{
    public override void OnBeforeCompleteType(ITypeCompletionContext completionContext, DefinitionBase? definition, IDictionary<string, object?> contextData)
    {
        if (definition is ObjectTypeDefinition objectDefinition)
        {
            foreach (var fieldDefinition in objectDefinition.Fields)
            {
                if (fieldDefinition.Arguments.Count > 0)
                {
                    fieldDefinition.MiddlewareComponents.Add(FieldClassMiddlewareFactory.Create<ValidationMiddleware>());
                }
            }
        }
    }
}

Using our new type interceptor is as easy as the following.

services.AddGraphQLServer()
    .TryAddTypeInterceptor<ValidationTypeInterceptor>()
    ...

We’ve now created our “pit of success”, we no longer need to rely on developers to remember to apply the correct middleware at the correct times, we can by convention apply it to the correct places.

Why doesn't GraphQL "SELECT *"

Fri, 20 Aug 2021 00:00:00 +0000

Over the last year or so I’ve helped onboard a number of engineers at Pushpay to how we do GraphQL. One question that often comes up is

How can I select all fields on a type?

GraphQL doesn’t have the equivalent of SELECT * FROM Object, you can only get the fields in the response that are in the query that was sent and in my opinion this is a very good thing. So why is that?

The major reason for me is the ability to make safe breaking changes to a schema. Occasionally (ideally as little as possible) we’ll need to make a breaking change to a schema, the way we tend to approach these schema changes is a pair of widening and narrowing changes. To use an exmaple we want to change the type of a field, for instance let’s assume we had a type Payment with had an amount field of type Decimal, however now we want to include the curreny as well and it makes sense to tie into the amount. A typical approach would look like:

Add new field amountPaid to Payment with an object type that includes amount and currency. It’s worth nothing that we can’t share field names so naming the new field can often be problematic, you may end up with a temporary name and run a second migration to rename the field back to the original. At the same time we can mark the amount field with @deprecated(reason: "Use amountPaid").

Now that we have marked the field as deprecated in the schema we can add some functionality to our backend. We’ve added a DiagnosticEventListener that logs any usage of a deprecated field, the include things like API client ids, user agents etc to help track down who is still selecting the deprecated field. This lets use target communication better about how to inform around these changes and monitor ongoing usage of that field.

Once we’re no longer seeing log messages around usage of the field we can safely remove the field from the schema knowing we won’t break functionality of a client.

Now if we had SELECT * and our clients were being lazy and decided to use this we wouldn’t be able to tell if a client actually cared about the amount field, or was just selecting all fields. This would mean we couldn’t communicate effectively with our clients nor determine when it was safe to make the breaking change.

All in all a good design decision.

GraphQL Observability

Wed, 04 Aug 2021 00:00:00 +0000

Whenever we have a web application we’ll typically want to be able to observe it in production. Typically common questions will be:

Which endpoints are being exercised the most?
Which endpoints are running slower than normal?
Which endpoints are returning errors to our users?

Eagle eyed readers will notice all of these quetsions are about endpoints or routes. Most Application Performance Monotiring (APM) products will have a built in knowledge of HTTP and easily be able to show this to you. New Relic which I’ll use for the rest of my examples even has an understanding of MVC built in and will classify transactions (requests) using their controller and action names rather than just the url.

What about GraphQL?

The way a GraphQL server works is that all queries and mutations are POST’s to the same url (typically something like /graphql) which means you get something like the following in New Relic.

Now this data won’t let you answer any of those three questions, and in fact GraphQL comes with even more nuance if you’re running a public GraphQL API which we can discuss another time.

Adding Observability

The Hot Chocolate has the concept of a DiagnosticEventListener, what we’ll do is create our own NewRelicDiagnosticEventListener to append some extra information to the current transaction to make it more useful.

The DiagnosticEventListener class has a number of methods you can override depending on what you care about in terms of your diagnostics. For this exacmple we care about ExecuteRequest.

public class NewRelicDiagnosticEventListener : DiagnosticEventListener
{
    public override IActivityScope ExecuteRequest(IRequestContext context)
    {
        // implementation goes here
    }
}

Now the API pattern for the DiagnosticEventListener is an intersting one that I’d never come across before and it’s worth a bit of explanation. Typeically for these diagnostic API’s we’ll need a hook for the start of a request as well one at the end as sometimes you’ll want to set up things at the start of the requuest and then collect / use them at the end. This can make a hefty API surface if for every “event” there would need to be two hooks. The Hot Chocolate developers resolved this by introducing IActivityScope which is simply a rename of IDisposable.

public interface IActivityScope : IDisposable
{

}

The idea is the framework will call ExecuteRequest at the start of the request. We’ll then request an IActivityScope that will be disposed by the framework at the end of the request.

For our example we’ll want to do changes to the New Relic transaction at the end of the request because we’ll want to use information parsed from the request body.

Here’s our final version, it returns a custom RequestActvityScope that on disposale will set the name of the current transaction in New Relic to be the incoming operation name.

public class NewRelicDiagnosticEventListener : DiagnosticEventListener
{
    public override IActivityScope ExecuteRequest(IRequestContext context)
    {
        return new RequestActvityScope(context);
    }

    private class RequestActvityScope : IActivityScope
    {
        private readonly IRequestContext context;
        private bool _isDisposed;

        public RequestActvityScope(IRequestContext context)
        {
            this.context = context;
        }

        public void Dispose()
        {
            if (_isDisposed)
                return;

            NewRelic.Api.Agent.NewRelic.SetTransactionName("GraphQL", context.Operation?.Name?.Value ?? "unknown");

            _isDisposed = true;
        }
    }
}

We can then use it with our setup code

services.AddGraphQLServer()
    .AddDiagnosticEventListener<NewRelicDiagnosticEventListener>()
    .AddQueryType<Query>();

Now we’ll see something more useful in New Relic, all our traffic previously grouped up in /graphql has been broken apart into the different operations our front end code is making which makes it a lot easier to answer the questions from the start of the post.

Conclusion

Out of the box most APM tools will do a poor job of observability into GraphQL operations due to how HTTP is used. We need to do more work on our server to assist the APM to enable us as developers to support our GraphQL API’s in production.

Implementing resource based authorization in GraphQL

Fri, 26 Feb 2021 00:00:00 +0000

Late last year I wrote about Securing a GraphQL endpoint, using ASP.NET Core policy based authorization.

The short version of this is that we can create authorization policies and use Hot Chocolate to apply those policies to fields in our schema. If the current user cannot fufill those policy requirements then the execution of that field is stopped and null is returned. It’s impotant to note that this doesn’t stop the entire query but just the field in question.

What is “resource based authorization”?

All of the examples used in the above articles we can think of “declarative authorization” where able to simply annotate the schema with our authorization requirements.

Sometimes however we need to take into account the data (or resource) in question needs to be taken into account. Microsoft terms this resource based authorization or “imperative authorization”.

Examples of this include:

Only the author of the document can edit it.
When viewing customer details if they are a minor then a specific permission is required.

You’ll notice that in that article the solution involves adding code to particular MVC actions to enforce thse policies.

An implementation in GraphQL

Authorization in the resolver

We can follow a similar implementation model in GraphQL as shown in the above article in MVC. This would be how we add the policy evaluation is the resolver for the field.

public async Task<Document> GetDocument(IResolverContext context, Guid documentId)
{
    // Hot Chocolate pushes the current user into `ContextData`
    var user = (ClaimsPrincipal) context.ContextData[nameof(ClaimsPrincipal)];

    var document = await _repository.Find(documentId);

    var authResult = await _authorizationService.AuthorizeAsync(user, document, "EditPolicy");

    return authResult.Succeeded ? document : null;
}

In this code we can reuse the requirement and requirement handlers in the article which is quite nice.

Creating a more reusable policy

We can implement this in another way in Hot Chocolate 11 which I think puts in a better place, the change they’ve added is an option to the @authorize directive which controls whether the policy evaluation occurs before or after the resolver (the only and now default behavior was before the resolver). This coupled with the fact that Hot Chocolate injects the IDirectiveContext as the reource being evaluated.

We can then modify the requirement handler as follows, here we look at the result of the resolver to get the document and run the same check as we did before.

public class DocumentAuthorizationHandler : 
    AuthorizationHandler<SameAuthorRequirement, Document>
{
    protected override Task HandleRequirementAsync(AuthorizationHandlerContext context,
                                                   SameAuthorRequirement requirement,
                                                   IMiddlewareContext middleware)
    {
        if (middleware.Result is Document document && context.User.Identity?.Name == document.Author)
        {
            context.Succeed(requirement);
        }

        return Task.CompletedTask;
    }
}

We can now apply our “imperative policy” is a declarative fashion as follows.

type Query {
    document(id: ID!): Document @authorize(policy: "EditPolicy", apply: AFTER_RESOLVER)
}

One of the major benefits of this approach is I can then easily apply this policy on multiple fields in our schema rather than having to go through our entire code base and inject the code. Even more useful is the ability to apply the directive to types which applies the policy to all fields on the type.

Conclusion

With the changes in Hot Chocolate 11 controlling when authorization directives are applied can let use build policies that implement “resource based authorization” in way that can be used across the entire schema.

Implementing GraphQL Relay Node support in Hot Chocolate

Mon, 25 Jan 2021 00:00:00 +0000

What is Relay?

The GraphQL spec isn’t very prescriptive on the structure of your schema leaving the design completely in your hands. This means we’re likely to see quite a few different approaches to certain patterns between different services. One specification that has become pretty common across services is Relay.

If you check out their webpage you’ll notice that it advertises itself with

Relay is a JavaScript framework for building data-driven React applications powered by GraphQL, designed from the ground up to be easy to use, extensible and, most of all, performant. Relay accomplishes this with static queries and ahead-of-time code generation.

In order to achieve this Relay has to make some assumptions about the structure of your GraphQL service, these are documented at GraphQL Server Specification. We won’t described it in detail here but ultimately it covers three areas.

Being able to fetch arbitrary objects by id.
Paging one to many relationships between objects.
Mutation inputs and paylods.

For this post we’ll cover implementing part of this specification using Hot Chocolate, in particular the first requirement around arbitrary objects by id.

The server specific defines an interface Node to designate service objects and being able to accessed globally by id.

interface Node {
    id: ID!
}

Objects implementing this interface may look something like

type Product implements Node {
    id: ID!
    name: String!
    category: ProductCategory!
}

type Order implements Node {
    id: ID!
    customer: Customer!
    createdOn: Instant!
}

The specification also defines a top level query field that takes an ID and returns a Node.

type Query {
    node(id: ID!): Node
}

This would allow to construct queries that look like

query {
    node(id: "Tm90aWZpY2F0aW9uCmQxNTox") {
        id
        ... on Product {
            name
            category
        }
    }
}

It should be obvious from this that the id values for each our nodes should be globally unique.

So what’s the value here? This patterns means we may not need to build top level fields to query different objects by id but all can go through this node field. In provides standards around identifiers as well.

Implementing in Hot Chocolate

Our first step will be enabling Relay functionality on our server, this is done during our server setup.

 services
    .AddGraphQLServer()
    .EnableRelaySupport()
    .AddQueryType<QueryType>();

Once this is done we can no add Node support to any of our types. Let’s assume we have a ProductType class describing Product.

public class ProductType : ObjectType<Product>
{
     protected override void Configure(IObjectTypeDescriptor<Product> descriptor)
     {
         descriptor
            .ImplementsNode()
            .IdField(n => n.Id)
            .ResolveNode(async (context, id) =>
            {
                var productRepository = context.Service<IProductRepository>();

                return await productRepository.GetById(id);
            });
     }
}

Here we’re doing three things.

Saying that Product will implement the Node interface.
Describe which property on the Product will be used for the Node.id.
A resolver to take the id and return the Product.

So what is Hot Chocolate doing here?

It’s adding a field id to the Product object the resolves to creating a globally unique identifier. It does this by encoding the type information into the id. For instance if internally our product id was the integer 42 then on our GraphQL service the id value will look something like UHJvZHVjdAppNDI= which decoded includes the type as well as the id. This also means that when the a query to the node field is resolved because the id contains the type information then it can route the query to the resolver in question.

In later posts we’ll talk about connections and mutations.

Custom GraphQL scalars

Thu, 17 Dec 2020 00:00:00 +0000

With the release of Hot Chocolate 11 comes a very slimmed down approach to building custom scalars in GraphQL.

What are custom scalars?

In GraphQL fields can be complex types such as objects, interfaces and lists or they can be scalar values. The GraphQL spec lists all the built in scalars such as ID, Int and String. However we also have the ability to define our own custom scalars, we do this because we want to be able to take advantage of the strong type system that GraphQL provides. With custom scalars we can:

Make invalid data for types an error before it even reaches your resolvers.
Better express our domain model to clients.
Enable client side type generation to be richer.

What are some examples of custom scalars

One of the standout examples is that the spec doesn’t support any date / time scalar out of the box, we could use String but then we need to ensure it’s a valid string everywhere that takes an input and can potentially be harder to enforce a consistent output. While Hot Chocolate does come with a DateTime scalar we at Pushpay decided to model a scalar around the Instant from NodaTime in order to make it every clear about how we’re dealing with things like timezones.

Other examples could be for object identifiers, again the spec comes with support for ID it can have its own problems. For instance we often see fields with argument signatures that look something like

type Query {
    communityMember(organizationID: ID! communityMemberID: ID!): CommunityMember
}

It can be far too easy to put the wrong id into the wrong argument when all ID types are the same, with different types this becomes a validation error.

Defining our custom scalar

In Hot Chocolate 10 there was a decent amount of work to build a custom scalar, but now in v11 it’s become a lot simpler. Let’s take a look at the code for our Instant custom scalar:

public class InstantType : ScalarType<Instant, StringValueNode>
{
	public InstantType() : base(nameof(Instant))
	{
	}

	public override IValueNode ParseResult(object? resultValue) =>
		resultValue switch
        {
			Instant i => ParseValue(i),
			null => NullValueNode.Default,
			_ => throw new SerializationException("Could not parse Instant", this)
		};

	protected override Instant ParseLiteral(StringValueNode valueSyntax) => InstantPattern.ExtendedIso.Parse(valueSyntax.Value).Value;

	protected override StringValueNode ParseValue(Instant runtimeValue) => new StringValueNode(InstantPattern.ExtendedIso.Format(runtimeValue));
}

We’re obviously inheriting from ScalarType but what’s interesting is the two type arguments, the first is the underlying dotnet type for this scalar often referred to by the framework as the “runtime type”. The second argument is how this will be represented in parsed GraphQL. This can sound complex if we imagine passing our scalar as an argument without a variable what might it look like? For our Instant and the example below you can see we’ll be using a StringValueNode, I suspect a majority of custom scalars would be, but things like IntValueNode may also make sense.

query {
    payments(after: "020-12-14T01:19:50Z") {
        amount
    }
}

In the constructor we pass the name our scalar to the base constructor. This affects the name in the final schema:

scalar Instant

From there we define a couple of different parse methods to handle converting between the runtime value and the literal value in a way that should be reasonable obvious.

Using our new scalar

The best way to use our custom scalar is to add it directly to the schema.

services.AddGraphQLServer()
    .AddType<InstantType>();

Now any of our C# types that have Instant properties where Hot Chocolate is automatically disovering fields will now use our custom scalar.

public class Payment
{
    public Instant OccurredOn { get; set;}
}

type Payment {
    occurredOn: Instant!
}

scalar Instant

Securing a GraphQL endpoint

Wed, 11 Nov 2020 00:00:00 +0000

One of the first things we’ll typically want to do when building out any API whether its’ GraphQL or REST is to secure it against users who should not have access to it.

I’ve seen a few articles about this recently when it comes to GraphQL but these are usually about securing the entire /graphql endpoing with a single authentication / authorization policy which isn’t very nuanced, especially given the nature of GraphQL.

Defining requirements

Let’s start by definining our requirements for authentication and authorization.

A valid JWT is required to be authenticated. This includes validating claims such as issuer and audience of the token.
All queries / mutations (including introspection) must require authentication.
The JWT token should contain scope claims.
Some fields on our schema require specific scopes to access.

Authentication

Looking at the list above for authentication there’s nothing specific to GraphQL here so we should be able to use the out of the box ASP.NET Core functionality that looks something like:

services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options => Configuration.Bind("JwtSettings", options));

app.UseAuthentication();

With the above we’re able to correctly authenticate users with the provided JWT token but we’re not yet applying it to any requests. Let’s start with fufilling requirement 2.

Authenticating all queries / mutations

Assuming we’re using Hot Chocolates code first approach then we’ll simply call Auhorize with no parameters on the root query type. By providing no role or policy names we’re simply saying the user must be authenticated to access any fields on this type. Since this is the root query type we’re not authenticating all queries (including the introspection queries). We can complete a similar addition to the root mutation type.

public class QueryType : ObjectType<Query>
{
	protected override void Configure(IObjectTypeDescriptor<Query> descriptor)
	{
		descriptor.Authorize();

        // field definitions are here
    }
}

Authorization

Now we have working authentication let’s work on authorization, for the purposes of this example I’m going to assume our JWT includes some claims called scope which are the parts of the schema the authenticated user. We’ll assume our scope values look something like document:read, document:write and so on.

We’re going to be using policy based authorization, so the first we’ll need to do is create some policys that enforce the scopes. In the example below we’re defining all our policies upfront, given the number of scopes we’re enforcing this is ok but as the list grows it may not be the best approach. In a later post I’ll write something up about dynamic policies.

services.AddAuthorization(options => {
	options.AddPolicy("scope:document:read", p => p.RequireClaim("scope", "document:read"));
	options.AddPolicy("scope:document:write", p => p.RequireClaim("scope", "document:write"));
});

public class MutationType : ObjectType<Mutation>
{
	protected override void Configure(IObjectTypeDescriptor<Mutation> descriptor)
	{
		descriptor.Authorize();

        descriptor.Field(m => m.CreateDocument(default!))
            .Argument("input", a => a.Type<NonNullType<CreateDocumentInputType>>())
            .Type<DocumentType>()
            .Authorize("scope:document:write");
    }
}

In the above code you can see us applying the @authorize diretive to the field createDocument and specifying the policy to enforce when the mutation is called.

One question that comes up often is:

If we’re enforcing the policy on the createDocument field what’s the point of the authentication on the mutation type?

In the above example the type level directive doesn’t add any more security, but it allows to create a “secure by default” position. If another developer who hasn’t had their morning coffee comes along adds a new mutation to the type but forgets to add the polcy rules then at least the user but still be authenticated to call the mutation and it’s not open to the big bad internet.

Multiple policies

One of the benefits to using policies and GraphQL is that we don’t need to just apply our policies on the root query and mutation fields, but use them across our entire schema.

type Document {
    id: ID!
    title: String!
    history: [DocumentHistory!] @authorize(policy: "scope:document:read:sensitive")
}

Here we’re apply a policy enforcing a policy requiring a narrower scope to a particular field on the document, so what would happen if a user had the scope document:read but not document:read:sensitive and tried to query the history?

They would receive the data they are alloed to access such as id and title, but history would be null and the errors collection of the response would include an error referring to the history field.

GraphQL Naming Conventions

Thu, 08 Oct 2020 00:00:00 +0000

The Hot Chocolate GraphQL framework does an excellent job building a schema from your C# types by convention. An easy example would be to see a C# type such as:

public class User
{
    public string Username { get; set; }
    public string? Name { get; set; }
    public bool IsVerified { get; set; }
}

and it will build a GraphQL object that looks like the following:

type User {
    username: String!
    name: String
    isVerified: Boolean!
}

One point to notice is that differences in casing between C# properties and GraphQL field names, this is where we have a difference in naming / casing conventions between the two systems. Normally the out of the box conventions are fine but sometimes we may want to finesse them a bit. This could be because your company already has some conventions agreed upon, or you just plain don’t like the out of the box ones.

For us at Pushpay one of the things we disagreed was the out of the box enum values convention. By default if you have an enum that looks like:

public enum PaymentMethodType
{
    CreditCard
    ApplePay
    AchBankAccount
}

then Hot Chocolate will create you a enum that looks like

enum PaymentMethodType {
    CREDITCARD
    APPLEPAY
    ACHBANKACCOUNT
}

Now if we look at the GraphQL specification concerning enums then it doesn’t really make it clear what multi word enum value casing should be. It’s only when we look at the enums that represent directive location that we see the convention is what we affectionately call “Screaming Snake Case”.

For us one of the other benefits of this change in case is how it affects TypeScript generation based off the schema where CREDITCARD becomes Creditcard but CREDIT_CARD becomes CreditCard.

Now we could just go and hard wire these changes into all of our enum types but there’s also a chance one may be missed and fixing them after they’re in use is a painful topic for another blog post.

Thankfully Hot Chcolate has built in support for schema wide customization of naming conventions through the INamingConventions interface.

To fix our example above we’ll make use of the Humanizer library.

public class PushpayConventions : DefaultNamingConventions
{
	public override NameString GetEnumValueName(object value) => value.ToString().Underscore().ToUpperInvariant();
}

We simply register this class into our services as normal:

services.AddSingleton<INamingConventions, PushpayNamingConventions>();

Now we’ll get our “screaming snake case” for enums by default and no chance of one “falling through the cracks.

I’d encourage you all to check out the entire interface and seeing else you may want to customize.

public interface INamingConventions
{
    string GetArgumentDescription(ParameterInfo parameter);
    NameString GetArgumentName(ParameterInfo parameter);
    string GetEnumValueDescription(object value);
    NameString GetEnumValueName(object value);
    string GetMemberDescription(MemberInfo member, MemberKind kind);
    NameString GetMemberName(MemberInfo member, MemberKind kind);
    string GetTypeDescription(Type type, TypeKind kind);
    NameString GetTypeName(Type type);
    NameString GetTypeName(Type type, TypeKind kind);
    bool IsDeprecated(MemberInfo member, out string reason);
    bool IsDeprecated(object value, out string reason);
}

Dynamic GraphQL Schemas

Thu, 10 Sep 2020 00:00:00 +0000

Declaring our schema

When we build a GraphQL service we define our schema, we typically do this via two different mechanisms. The first is often referred to as schema first where we declare the schema using the SDL that may look something like:

type Query {
    product(id: ID!): Product
}

type Product {
    id: ID!
    name: String!
}

The the other approach is usually referred to as code first which will look very different depending on which GraphQL server framework you’re using, below is an example from the excellent .NET GraphQL framework Hot Chocolate.

public class QueryType : ObjectType<Query>
{
    protected override void Configure(IObjectTypeDescriptor<QueryType> descriptor)
    {
        descriptor.Field(q => q.Product(default!, default!))
            .Argument("id", a => a.Type<NonNullType<IdType>>())
            .Type<ProductType>()
    }
}

This post isn’t going to debate the pros & cons of the two above approaches, they both have strengths and weaknesses but I generally prefer code first. There’s dozens of articles about this on the internet if you want to read more.

A surprising benefit of the code first approach

If you have gone and looked at some of the articles discussing the code first approach one thing may strike you, it’s a very declarative approach, we’re using code to create the schema but we’re still creating new code when new types come along. The question then becomes, is this always the case?

Strongly typed explosion

Recently at Pushpay I spiked some work on what a Notifications microservice would look like, a simple service that allowed other services to push notifications for users and allow applications to query the notifications for a specific user.

Obviously different notifications will have different metadata associated with that notification based on what sort of notification it is. When an export job has been completed processing then we’ll need the id of the export and potentially a link to the result.

It can be very easy when designing the GraphQL schema for this service to try and create a generic schema that can acoomodate all sorts of different types of notifications. Ultimately you’ll end up with something that looks like the following:

type Notification
{
    key: NotificationKey!
    createdOn: Instant!
    metadata: [MetadataItem!]!
}

type MetadataItem {
    key: String!
    value: String
}

While functional in my opinion it misses the point of GraphQL, why bother trying to build a generic not very type safe model on top of a strongly typed schema? It’s impossible to see from the schema what sort of notifications we receive nor what metadata they’ll have. My ideal schema would look something like:

interface Notification {
    key: NotificationKey!
    createdOn: Instant!
}

type ExportCompleted implements Notification {
    key: NotificationKey!
    createdOn: Instant!
    exportKey: String!
    sucessful: Boolean!
}

Now this is where the “type explosion” I mentioned in the header for this section comes in. When I first started spiking what a fully strongly typed schema would look like I really had examine what each notification added to the schema it it’s entirety and came to the following list. Each notfication type would require (we’ll use a complete export for concrete examples):

The notification type itself that implements the interface ExportCompleted.

A mutation field that creates that notification.

createExportCompletedNotification(input: CreateExportCompletedInput!): ExportCompletedResult!

A input to the above mutation that includes the metadata specific to that notification.

input CreateExportCompletedInput {
  exportKey: String!
  sucessful: Boolean!
  # common notification fields such as who it's for here
}

A result class of that mutation that handles returning the strongly typed mutation payload.
```
type ExportCompletedCreated {
  notification: ExportCompleted!
}
```
A union of the above payload and validation errors (it’s a post for another day but we represent validation errors in the schema).
```
union ExportCompletedResult = ExportCompletedCreated | ValidationErrors
```

Not a huge list but the idea that every developer that wants to add a new notification type has to create five different types and a new mutation isn’t attractive, it’s high friction and quite a waste of time.

Rather than using declarative code first can we dynamically create the above types without requireing a mountain of work?

Defining the definition

First we start with our “source of truth” for nofications, below is a stripped down example of a NotificationDefinition class. This is the declarative piece of the puzzle that provides the data for the type generation below, for your needs it could come from anywhere including a database.

 public class NotificationDefinition
 {
	readonly List<(string, Type, bool)> _data = new List<(string, Type, bool)>();

	public static readonly IReadOnlyCollection<NotificationDefinition> All = new List<NotificationDefinition> {

		new NotificationDefinition("ExportCompleted")
			.WithMetadata<string>("ExportKey", required: true)
			.WithMetadata<bool>("Successful", required: true)
	};

	public NotificationDefinition(string name)
	{
		Name = name.Pascalize();
	}

	public string Name { get; }

	public IReadOnlyCollection<(string, Type, bool)> Metadata => _data;

	public NotificationDefinition WithMetadata<T>(string name, bool required)
	{
		_data.Add((name.Camelize(), typeof(T), required));

		return this;
	}
 }

Now instead of trying to declare our types in code we’re going to write some code that uses this definition and creates the types for us. This code is going to be very Hot Chocolate specific but hopefully the concept applies across other frameworks just as well. Here’s we’re iterating over our definitions and creating a new ObjectType, giving it the correct name, implementing the interface and then adding the correct fields based on the common fields and then the specific fields for that definition. The last step is then registering that type within the schema.

public static ISchemaConfiguration RegisterNotificationTypes(this ISchemaConfiguration configuration, IEnumerable<NotificationDefinition> definitions)
{
    foreach (var definition in definitions)
    {
        var notificationTypeName = definition.Name;

        var notificationType = new ObjectType(d => {

            d.Name(notificationTypeName).Implements<NotificationType>();

            d.Field("key").Type<NonNullType<NotificationKeyType>>().Resolver(c => c.Parent<Notification>().Key);
            d.Field("createdOn").Type<NonNullType<InstantType>>().Resolver(c => c.Parent<Notification>().CreatedOn);

            foreach (var (name, type, required) in definition.Metadata)
            {
                var fieldType = required ? (ITypeNode)
                    new NonNullTypeNode(new NamedTypeNode(type.Name)) :
                    new NamedTypeNode(type.Name);

                d.Field(name)
                    .Type(fieldType)
                    .Resolver(c => c.Parent<Notification>().Metadata[name]);
            }
        });

        configuration.RegisterType(notificationType);
    }

    return configuration;
}

We won’t show creating all five pieces listed above, most follow similar patterns to the above code. The one interesting one is the mutation field. Here we’ll register an ObjectTypeExtension that extends our MutationType definined elsewhere. This means we can keep the whole definition self contained.

configuration.RegisterType(new ObjectTypeExtension(d => 
    {
		d.Name("Mutation");

		d.Field($"create{notificationTypeName}Notification")
			.Type(new NonNullTypeNode(new NamedTypeNode(mutationResultTypeName)))
			.Argument("input", a => a.Type(new NonNullTypeNode(new NamedTypeNode(mutationInputTypeName))))
			.Resolver(c => c.Resolver<Mutation>().Create(c, definition));
    }));

Summary

A lot of the code above isn’t neccesary to understand, the idea we’re trying to get across here is that we can use code first approach lets us not just use a declarative schema but build ourselves a data driven schema that’s built at start up.

Stepping away from Caliburn.Micro

Thu, 18 Jun 2020 00:00:00 +0000

Background

This has been a hard post to write and probably a few years over due, but human nature being what it is has delayed it longer than it should have.

Roughly eight years ago I started working at a company Marker Metro that was founded around building great Windows apps both on the desktop and phone. This was about the time of the Windows 8 launch, we were fortunate to be working with a number of launch partners and have access to early builds of Windows 8 in order to have apps in the store when the OS launched. Back then I had used Caliburn.Micro (at the time created and maintained by Rob Eisenberg) on some WPF, Silverlight and WP7 projects and wanted to use it in Windows 8. By then Rob had moved on to working mostly with Durandal so I spent some of my time at work porting CM across to Windows 8 and submitted the PR.

These PR’s ultimately led to me to take over maintenance of the CM project and over time add support for UWP and Xamarin.Forms. I’ve been very lucky with this opportunity, maintaining a popular open source project lead to many other opportunities that really snowballed, being able to speak internationally as well as the award of a Microsoft MVP for five consecutive years. I was also lucky in that my work at the time supported working on Caliburn.Micro as part of my day job.

But four years ago I moved on to a different job that wasn’t apps focused and the only time I had to work on Caliburn.Micro was late in the evening. At this point my family had grown and spare time was even more precious, for a long time I thought I could keep it up and be able to support the project even when I wasn’t using it on a day to day basis in my evenings. History has shown that it wasn’t going to happen, the time for 4.0 to be created and released is ample proof of that and I’ve put off writing this post for probably two years.

What now?

Over the next few weeks I’ll be doing the following.

Publishing a release candidate of 4.0 and as long as nothing crazy comes up will be published as the final version. I’m a little undecided on the last part as the documentation will be very out of date at that point and this may cause more confusion that it’s worth.
I’ll continue to pay for the domain so the website won’t disappear but will be updated to reflect the state of the project.
If someone is willing to step up and help maintain the project reach out and we can discuss a transition plan.

I’d like to thank everyone who’s helped me with this project over the years.