Query execution-time schema elements

[mroach]

A bit of quick background. Our application is multi-tenant. The vast majority of the schema is static, but customers have the option of configuring custom fields that can attach to different record types. This allows them to store data they want to see on screens and export. These fields can be a number of different data types: strings, ints, dates, attachments, money, or record references.

Until now we've worked with this in GraphQL by using union types. This works and works well for our web app, but for a user at a customer writing their own queries, the interface is terribly cumbersome. Queries end up looking like this, except even more complex to fulfil all the types:

query {
  users {
    nodes {
      customFieldValues {
        customField { name }
        ... on BooleanFieldValue { boolValue: value }
        ... on StringFieldValue { stringValue: value }
        ... on RelationFieldValue {
          value {
            ... on User { email }
            ... on Category { code }
          }
        }
      }
    }
  }
}

I'd like to simplify this interface for customers using our API.

I've got a working prototype of this, but any time I'm overriding so many default methods, I feel like I may be barking up the wrong tree, so I'm hoping for some help sanity-checking this.

The strategy is generating types for a given field's parent type, and then having everything else be context-aware so fields are pulled from the database and cached for the right account.

Type Generator

class Types::CustomFieldValues < GraphQL::Schema::Object
  field_class(Types::BaseField)
 
  class << self
    def generate_for(parent_type)
      klass = Class.new(self)
      klass.graphql_name("#{parent_type_name}CustomFieldValues")
      klass.define_singleton_method(:parent_type_name) { parent_type_name }
      klass.instance_variable_set(:@schema_mutex, Mutex.new)
      klass
    end

    def fields(context)
      # Ensure all the fields are defined
      usable_custom_fields(context).each do |name, _|
        get_field(name, context)
      end

      own_fields(context)
    end

    def own_fields(context = nil)
      return {} if context.nil?

      @own_fields ||= {}
      @own_fields[context.fetch(:tenant_id)] ||= {}
    end
 
    def get_field(name, context)
      # Once upon a time we had intermittent "already defined" errors when doing
      # schema generation like this and a mutex like this fixed it.
      @schema_mutex.synchronize do
        if (field_def = own_fields(context)[name])
          return field_def
        end

        spec = usable_custom_fields(context).fetch(name)
        spec => {id: custom_field_id, graphql_type:}

        # To avoid potential conflicts with built methods, generate a name.
        getter_name = "get_#{name}_value".underscore.to_sym
        define_method(getter_name) { custom_field_value_for(custom_field_id) }

        own_fields(context)[name] = field_class.from_options(
          name:,
          type: graphql_type,
          null: true,
          description: spec[:description],
          resolver_method: getter_name
        )
      end
    end

    private

    def usable_custom_fields(context)
      # Query the database for custom fields for this account and return a hash of them.
      #  e.g. CustomFields.where(tenant_id: context.fetch(:tenant_id)).to_h ...
     
      # Sample return value:
      {
        "projectNumber" => {
          graphql_type: GraphQL::Types::String,
          id:,
          description:
        }
        "dateHired" => {
          graphql_type: GraphQL::Types::ISO8601Datetime,
          id:,
          description:
        }
      }
    end
  end

  def custom_field_value_for(custom_field_id)
    # resolve the right value
  end
end

Then, the types that use custom fields can add them:

class Types::User < BaseObject
  field :custom_field_values, Types::CustomFieldValues.generate_for("User"), method: :itself
end

The question is: am I doing something I'm going to regret? Is there something I'm missing that will cause me pain if I do this?

[rmosolgo]

Wow, it's pretty wild, but not totally crazy 😆

I definitely imagined something like this with the fields/get_field methods, but I don't think anyone has actually built it yet. Definitely some people are doing this with Schema::Enum.values.

I think it's possible. The main thing that stood out to me was allocating memory during a request that won't be GC'd when the request is done. For example, define_method(...) will create a method in that Ruby process forever. If you have lots of tenants with lots of custom fields, it will gobble memory until the application is redeployed. Another possibility would be to use a Resolver class which uses field.graphql_name to infer a custom field to look up.

@own_fields[tenant.id] = {} has the same issue -- those hashes will grow during the lifetime of the Ruby process and never shrink back down.

It's not a deal-breaker -- especially if you know your customers' usage patterns well enough to know it's not a problem.

Another thing is that the cached fields and methods won't be reset when customers update their custom fields. The database will have new data, but @own_fields[tenant.id] will have stale data. Actually, it would depend on the Ruby process -- if the customer's request was routed to a process that had previously served their request, they would get stale data. But if the request went to a Ruby process which had not served a request for that customer, it would get fresh data. Then the next request might get stale data 😆 . You could add a Tenant#custom_field_version number which incremented whenever they updated their custom field configuration, and use it to bust the @own_fields cache.

Another issue is that customers will share methods. If one customer makes a custom field called zipCode that returns a String, but another customer makes a field called zipCode that returns an integer, there would only be one get_zipCode_value method in Ruby. Depending on how that method is implemented, it might end up returning the wrong type -- or wrong data -- to the client. But this might not be an issue depending on how custom_field_value_for is implemented.

The other thing is, I'd suggest extensive unit tests and benchmarks for this part of your API. I definitely don't expect to break the APIs you're using here, but I might overlook something! (I'd be open to including some tests for this usage in the gem, too, if you want to contribute them.) Also, other internal changes might hurt performance in ways that I can't yet imagine...

I hope this helps!

[mroach]

@rmosolgo Thank you for the feedback on this! Much appreciated.

I hadn't thought about the GC issue with defining methods; glad you pointed that out! I had looked to see if I could use a proc for a resolver, but using a Resolver class sounds like a good way to avoid defining methods.

The custom field configuration rarely changes, but I agree that change should be reflected immediately in the schema and definitely not vary between which instance is serving the request. I like the idea of a cache-busting version key, or even only caching for the duration of a request since at least in our case, the customer-facing API isn't used enough to the point where caching this would make an appreciable difference.

I would expect some kind of performance penalty for doing this, but I think the tradeoff will be worth it for our customers' ease of use (and our support of them). Fortunately these days provisioning a new server means editing some k8s config :D

I'll get busy turning this MVP into a production-ready solution, replete with tests to ensure there's no cross-thread or cross-request issues going on. If it all pans out, I'll be happy to submit the final results for consideration in documentation :)