nulogy_message_bus_producer 1.0.4 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1584c82f65b0be1d4b508359a88720ac4b2b1ec6a7fc82982043de1dfdfb476c
-  data.tar.gz: 85adbd1344cebbbc4a2c160c54b94cd2227479c51432422c399d2ad99ea6107a
+  metadata.gz: 54bcc4198672edd1d3366678b06118df437c95267fd274f1df2969d5e029abff
+  data.tar.gz: 5c4a2d3dd70682348e383a0398e48944845512fcb6a68478278e76b5f5ac3153
 SHA512:
-  metadata.gz: bdaba4ee6796bdb31e937d5e9d13504a22e57e9f9ef32d03a8bcb62a68e94c089a9fcfba65284d93312409e32cfb63b3127d23129e897b7c3b43e5c6b32900bb
-  data.tar.gz: ccdb3e8363346ace7041cf1604a61ea15726247520de4d650eff21ee45bd8b8b2d369b239d5ab449a9d7938825204b13fbd4b304a0175b351915fc3ecf7486f4
+  metadata.gz: 04707ec3c4da493d52a4d817da040a88fb32dc3017cb549098e7a1d38d47a8ba24a34d707382c7391822fe640c0bd2792f540acb826da8eb4300a5e3482caaca
+  data.tar.gz: a27eabba49d13fabae89628f1210232b7f46ce28c41514e1fc86d3ac344af8e8c650517dd76c7141a290f625474adcf34bb1ff11209a542d49d34194c5b08bcc

data/README.md

@@ -11,7 +11,7 @@ Nulogy's code for producing to to the Message Bus
 
 This engine contains the classes and validations for producing messages to the Message Bus.
 
-In general, as long as a subscription inherits from `NulogyMessageBusProducer::BasePublicSubscription`, everything
+In general, as long as a subscription inherits from `NulogyMessageBusProducer::BaseSubscription`, everything
 should be set up.
 
 Subscriptions will be written to the `NulogyMessageBusProducer.subscriptions_table_name` while events generated from the subscriptions will be written to
@@ -19,34 +19,202 @@ Subscriptions will be written to the `NulogyMessageBusProducer.subscriptions_tab
 
 ## Configuration
 
-| Configuration                  | Default                         | Description                                                  |
-|--------------------------------|---------------------------------|--------------------------------------------------------------|
-| subscriptions_table_name       | message_bus_subscriptions       | The name of the table for the PublicSubscription model       |
-| subscription_events_table_name | message_bus_subscription_events | The name of the table for the PublicSubscriptionEvents model |
+| Configuration                  | Default                         | Description                                                                                 |
+|--------------------------------|---------------------------------|---------------------------------------------------------------------------------------------|
+| context_for_subscription       | `->(_subscription) { {} }`        | A lambda used to inject any GraphQL Context to be used when producing subscription events |
+| producing_events_fails_with    | :raise                            | How the producer should handle errors when producing subscription events                  |
+| subscriptions_table_name       | "message_bus_subscriptions"       | The name of the table for the Subscription model                                          |
+| subscription_events_table_name | "message_bus_subscription_events" | The name of the table for the SubscriptionEvents model                                    |
 
 ## Setup
 
 You should configure the gem with an initializer. A recommended setup:
 
-```
+```ruby
 # Table names are configurable (optional)
-NulogyMessageBusProducer.subscriptions_table_name = :public_subscriptions
-NulogyMessageBusProducer.subscription_events_table_name = :public_subscription_events
+NulogyMessageBusProducer.subscriptions_table_name = :message_bus_subscriptions
+NulogyMessageBusProducer.subscription_events_table_name = :message_bus_subscription_events
 
 # Register known schemas
-NulogyMessageBusProducer.register_schema("example_domain", "ExampleDomain::Schema")
+NulogyMessageBusProducer.configure do |config|
+  config.register_schema(schema: "ExampleDomain::Schema", key: "exampleDomain")
+
+  config.context_for_subscription = lambda do |_subscription|
+    {
+      current_user: Current.user,
+      current_company: Current.company
+    }
+  end
+
+  # Can fail with either :soft_fail or :raise
+  # :raise will cause the application to halt when event generation fails.
+  # :soft_fail will allow the application to continue, even if generating events fails.
+  # Be very careful when deciding on the behaviour.
+  # Using :raise can result in the application being unusable if a subscription cannot be fulfilled.
+  # Using :soft_fail can result in missing messages, and a lack of consistency between applications.
+  config.producing_events_fails_with(:soft_fail) do |subscription_id:, context:, variables:, result:|
+    # Log in Airbrake / Honeybadger
+    ExceptionNotifier.tagged_message(
+      message: "Generating an event failed!",
+      context: {
+        subscription_id: subscription_id,
+        context: context,
+        variables: variables,
+        result: result
+      }
+    )
+  end
+end
 
 # It is *strongly* recommended to run this validation
-# It ensures the query in a subscription is valid agains the current schema
+# It ensures the query in a subscription is valid against the current schema
 # If you do not run this, a change to the schema could break the app
 # Note: ensure to register schemas before running this
 NulogyMessageBusProducer.validate_existing!
 ```
 
+Additionally, your GraphQL Schema will need to use `NulogyMessageBusProducer::Subscriptions::PostgresTransport`, `NulogyMessageBusProducer::Subscriptions::RiskySubscriptionBlocker` and expose subscriptions and queries for the objects to be integrated. Below is an example of how to expose `:sku_created` and `:sku_updated` events.
+```ruby
+module ExampleDomainPublicApi
+  class Schema < GraphQL::Schema
+    use NulogyMessageBusProducer::Subscriptions::PostgresTransport
+
+    # You must use the Interpreter, as it will be the new default.
+    # See more here: https://graphql-ruby.org/queries/interpreter
+    use GraphQL::Analysis::AST
+    use GraphQL::Execution::Interpreter
+
+    # This prevents subscriptions which contain arguments or expand lists form being registered.
+    # Expanding unbounded lists inside of an event may severely impact the performance of the system.
+    # Arguments are a source of variation that may not be appropriately tested.
+    # For now, these are banned until we have a use-case which would require them.
+    query_analyzer NulogyMessageBusProducer::Subscriptions::RiskySubscriptionBlocker
+
+    query Types::QueryType
+    subscription Types::SubscriptionType
+  end
+end
+
+module ExampleDomainPublicApi
+  module Types
+    class QueryType < BaseObject
+      description "The query root for this schema"
+
+      field :sku, Types::SkuType, null: false do
+        argument :id, NulogyGraphqlApi::Types::UUID, required: true
+      end
+
+      def sku(id:)
+        Sku.find(id)
+      end
+    end
+  end
+end
+
+module ExampleDomainPublicApi
+  module Types
+    class SubscriptionType < Types::BaseObject
+      extend GraphQL::Subscriptions::SubscriptionRoot
+
+      description "The subscription root for this schema"
+
+      field :sku_created,
+        subscription: Subscriptions::SkuCreated,
+        description: "Event from creating a SKU. Tenancy is company.uuid"
+
+      field :sku_updated,
+        subscription: Subscriptions::SkuUpdated,
+        description: "Event from updating a SKU. Tenancy is company.uuid"
+    end
+  end
+end
+
+module ExampleDomainPublicApi
+  module Subscriptions
+    class SkuCreated < NulogyMessageBusProducer::BaseSubscription
+      field :sku, Types::SkuType, null: false
+    end
+  end
+end
+
+module ExampleDomainPublicApi
+  module Subscriptions
+    class SkuUpdated < NulogyMessageBusProducer::BaseSubscription
+      field :sku, Types::SkuType, null: false
+    end
+  end
+end
+
+module ExampleDomainPublicApi
+  module Types
+    class SkuType < Types::BaseType
+      field :code, GraphQL::Types::String, null: false
+
+      field :description, GraphQL::Types::String, null: true
+      field :setup_time, GraphQL::Types::Float, null: true
+      field :teardown_time, GraphQL::Types::Float, null: true
+    end
+  end
+end
+```
+
+Events would need to be triggered. Ideally, the underlying domain would be emitting domain events and the events would then be routed in the application layer to the GraphQL API. Where the domain is enemic, this could be done soley in the application layer. In either case, it needs to be invoked in the same transaction as the underlying service.
+```ruby
+class CreateSku
+  def initialize(company)
+    @company = company
+  end
+
+  def create(attrs)
+    sku = Sku.new(attrs.merge(company: company))
+
+    if sku.save
+      # This needs to be invoked within the same transaction as Sku.save
+      # Otherwise, the sku could be saved without the event being triggered
+      trigger_subscription(:sku_created, sku)
+    end
+  end
+
+  private
+
+  def trigger_subscription(event, entity)
+    object = {
+      uuid: entity.id,
+      company_uuid: entity.company_id,
+      context: {}
+    }
+
+    NulogyMessageBusProducer.trigger_event(ExampleDomainPublicApi::Schema, event, object)
+  end
+end
+```
+
+## Resending All Events to the Message Bus
+
+There is a rake task for resending all events that are currently in the producer's event tables to the message bus.
+It works by locking the table, deleting all of the events and re-inserting them. This ensures that order is preserved
+for both existing and newly created events. Unfortunately, the lock will halt most activity on the application server.
+
+```shell script
+# WARNING: THIS WILL LOCK THE EVENTS TABLE, AND BY EXTENSION ANY DOMAIN LOGIC WHICH EMITS EVENTS.
+# THIS IS INTENDED TO BE USED FOR DISASTER RECOVERY ONLY.
+
+rails message_bus_producer:repopulate_replication_slots
+```
+
 ## Rake Tasks
 
-| Rake command | Description    |
-|--------------|----------------|
-| (default)    | RSpec +RuboCop |
-| `spec`       | RSpec          |
-| `rubocop`    | RuboCop        |
+| Rake command | Description     |
+|--------------|-----------------|
+| (default)    | RSpec + RuboCop |
+| `spec`       | RSpec           |
+| `rubocop`    | RuboCop         |
+
+# Gem Development Setup
+
+If you are doing work on this gem you will want to:
+```shell script
+docker-compose up
+rake db:setup
+rake
+```

data/Rakefile

@@ -8,8 +8,6 @@ end
 APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
 
-Bundler::GemHelper.install_tasks
-
 require "rspec/core"
 require "rspec/core/rake_task"
 
@@ -20,3 +18,9 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: [:spec, :rubocop]
+
+require "rake/release"
+
+Rake::Release::Task.load_all do |spec|
+  spec.version_tag = "nulogy_message_bus_producer-v#{spec.version}"
+end

data/db/migrate/20201005150212_rename_tenant_id_and_public.rb

@@ -0,0 +1,6 @@
+class RenameTenantIdAndPublic < ActiveRecord::Migration[5.2]
+  def change
+    rename_column NulogyMessageBusProducer.subscription_events_table_name, :tenant_id, :company_uuid
+    rename_column NulogyMessageBusProducer.subscription_events_table_name, :public_subscription_id, :subscription_id
+  end
+end

data/lib/nulogy_message_bus_producer.rb

@@ -1,51 +1,82 @@
 require "graphql"
-require "strong_migrations"
 
+require "nulogy_message_bus_producer/config"
 require "nulogy_message_bus_producer/version"
 require "nulogy_message_bus_producer/engine"
 
 # The gem and its configuration
 module NulogyMessageBusProducer
-  mattr_reader :registered_schemas, default: {}
+  mattr_accessor :config, default: Config.new
+
+  def self.configure(options = {})
+    config.update(options) if options.present?
+    yield(config) if block_given?
+  end
 
   def self.subscriptions_table_name=(table_name)
-    NulogyMessageBusProducer::PublicSubscription.table_name = table_name
+    NulogyMessageBusProducer::Subscription.table_name = table_name
   end
 
   def self.subscriptions_table_name
-    NulogyMessageBusProducer::PublicSubscription.table_name
+    NulogyMessageBusProducer::Subscription.table_name
   end
 
   def self.subscription_events_table_name=(table_name)
-    NulogyMessageBusProducer::PublicSubscriptionEvent.table_name = table_name
+    NulogyMessageBusProducer::SubscriptionEvent.table_name = table_name
   end
 
   def self.subscription_events_table_name
-    NulogyMessageBusProducer::PublicSubscriptionEvent.table_name
+    NulogyMessageBusProducer::SubscriptionEvent.table_name
   end
 
-  def self.register_schema(schema_key, schema_name)
-    registered_schemas[schema_key] = schema_name
+  def self.context_for_subscription(subscription)
+    config.context_for_subscription(subscription)
+  end
+
+  def self.trigger_event(schema, event_type, root_object)
+    schema_key = NulogyMessageBusProducer.resolve_schema_key(schema)
+
+    subscriptions = Subscription.where(
+      event_type: event_type,
+      schema_key: schema_key
+    )
+
+    subscriptions.each do |subscription|
+      args = {
+        subscriptionId: subscription.id,
+        subscriptionGroupId: subscription.subscription_group_id,
+        topicName: subscription.topic_name
+      }
+      schema.subscriptions.trigger(event_type, args, root_object)
+    end
   end
 
   def self.resolve_schema(schema_key)
-    registered_schemas.fetch(schema_key) do
-      raise KeyError, <<~MESSAGE unless block_given?
+    if config.registered_schemas.key?(schema_key)
+      config.registered_schemas[schema_key].constantize
+    elsif block_given?
+      yield
+    else
+      raise KeyError, <<~MESSAGE
         The schema registry did not contain an entry for the schema key '#{schema_key}'.
 
         Please register the schema first with `NulogyMessageBusProducer.schemas.register(schema_key, schema)`
-      MESSAGE
 
-      yield
-    end.constantize
+        Schemas Registered:
+        #{config.registered_schemas.pretty_inspect}
+      MESSAGE
+    end
   end
 
   def self.resolve_schema_key(schema)
-    registered_schemas.invert.fetch(schema.class.name) do
+    config.registered_schemas.invert.fetch(schema.name) do
       raise KeyError, <<~MESSAGE
-        The schema registry did not contain an entry for the schema '#{schema.class.name}'.
+        The schema registry did not contain an entry for the schema '#{schema.name}'.
 
         Please register the schema first with `NulogyMessageBusProducer.schemas.register(schema_key, schema)`
+
+        Schemas Registered:
+        #{config.registered_schemas.pretty_inspect}
       MESSAGE
     end
   end
@@ -58,9 +89,9 @@ module NulogyMessageBusProducer
     return if validator.validate
 
     raise <<~MESSAGE
-      #{'#' * 80}
+      #{"#" * 80}
 
-      The GraphQL queries stored in public_subscriptions.query must always remain valid against the current schema.
+      The GraphQL queries stored in subscriptions.query must always remain valid against the current schema.
       If one is not valid, a domain event firing could fail and users would not be able to perform critical duties
       (e.g. adding production).
 
@@ -75,7 +106,7 @@ module NulogyMessageBusProducer
 
       #{validator.errors.join("\n")}
 
-      #{'#' * 80}
+      #{"#" * 80}
     MESSAGE
   end
 
@@ -94,9 +125,12 @@ module NulogyMessageBusProducer
     def subscriptions_exist?
       ActiveRecord::Base
         .connection
-        .exec_query(
-          "SELECT tablename FROM pg_tables WHERE tablename = '#{NulogyMessageBusProducer.subscriptions_table_name}' AND schemaname = 'public';"
-        ).present?
+        .exec_query(<<~SQL).present?
+          SELECT tablename
+          FROM pg_tables
+          WHERE tablename = '#{NulogyMessageBusProducer.subscriptions_table_name}'
+            AND schemaname = 'public';
+      SQL
     rescue # rubocop:disable Style/RescueStandardError
       false
     end
@@ -105,8 +139,10 @@ module NulogyMessageBusProducer
 end
 
 require "nulogy_message_bus_producer/application_record"
-require "nulogy_message_bus_producer/base_public_subscription"
-require "nulogy_message_bus_producer/postgres_public_subscriptions"
-require "nulogy_message_bus_producer/public_subscription"
-require "nulogy_message_bus_producer/public_subscription_event"
+require "nulogy_message_bus_producer/base_subscription"
+require "nulogy_message_bus_producer/subscription"
+require "nulogy_message_bus_producer/subscription_event"
+require "nulogy_message_bus_producer/repopulate_replication_slots"
 require "nulogy_message_bus_producer/subscriber_graphql_schema_validator"
+require "nulogy_message_bus_producer/subscriptions/postgres_transport"
+require "nulogy_message_bus_producer/subscriptions/risky_subscription_blocker"

data/lib/nulogy_message_bus_producer/{base_public_subscription.rb → base_subscription.rb}

@@ -5,7 +5,7 @@ module NulogyMessageBusProducer
   #  class AggregateRootCreated < NulogyMessageBusProducer::BasePublicSubscription
   #    field :aggregate_root, Domain::Public::Types::AggregateRootType, null: true
   #  end
-  class BasePublicSubscription < GraphQL::Schema::Subscription
+  class BaseSubscription < GraphQL::Schema::Subscription
     argument :subscription_id, ID, required: true
     argument :subscription_group_id, ID, required: true
     argument :topic_name, String, required: true

data/lib/nulogy_message_bus_producer/config.rb

@@ -0,0 +1,72 @@
+module NulogyMessageBusProducer
+  # Configuration for the gem
+  # This is a private class, so do not use it directly. Use the methods on NulogyMessageBusProducer.
+  class Config
+    FAILURE_MODES = [:raise, :soft_fail].freeze
+
+    attr_reader :registered_schemas
+    attr_writer :context_for_subscription
+
+    def initialize(options = {})
+      @registered_schemas = {}
+      producing_events_fails_with(:raise)
+
+      update(options)
+    end
+
+    def context_for_subscription(subscription)
+      @context_for_subscription ||= ->(_) {}
+      @context_for_subscription.call(subscription)
+    end
+
+    def register_schema(schema:, key:)
+      @registered_schemas[key] = schema
+    end
+
+    def producing_events_fails_with(mode, &block)
+      @event_error_handler =
+        case mode
+        when :raise
+          method(:raise_handler)
+        when :soft_fail
+          block || ->(_) {}
+        else
+          unknown_mode_error(mode)
+        end
+    end
+
+    def handle_event_generation_error(subscription_id:, context:, variables:, result:)
+      @event_error_handler.call(
+        subscription_id: subscription_id,
+        context: context,
+        variables: variables,
+        result: result
+      )
+    end
+
+    def update(options = {})
+      options.each { |key, value| public_send("#{key}=", value) }
+    end
+
+    private
+
+    def raise_handler(subscription_id:, context:, variables:, result:)
+      raise StandardError, <<~MESSAGE
+        A subscription event could not be produced for subscription #{subscription_id}
+
+        The GraphQL engine returned this response:
+
+        #{result.to_h}
+
+        context: #{context.inspect}
+        variables: #{variables.inspect}
+      MESSAGE
+    end
+
+    def unknown_mode_error(mode)
+      options = FAILURE_MODES.map(&:inspect).join(", ")
+
+      raise ArgumentError, "The failure mode `#{mode}` is not valid. The modes are: #{options}."
+    end
+  end
+end