Merge pull request #539 from procore-oss/jh/rack-inspired-hooks

V2 Extensions as Middleware

Author: jhollinger

lib/blueprinter/errors/extension_hook.rb

@@ -3,12 +3,10 @@
 module Blueprinter
   module Errors
     class ExtensionHook < StandardError
-      attr_reader :extension, :hook, :message
+      attr_reader :message
 
       def initialize(extension, hook, message)
-        @extension = extension
-        @hook = hook
-        @message = message
+        @message = "Extension hook error in #{extension.class.name}##{hook}: #{message}"
       end
     end
   end

lib/blueprinter/extension.rb

@@ -7,49 +7,29 @@ module Blueprinter
   # V2 hook call order:
   #
   # - around_hook (called around any other extension hook)
-  # - blueprint
-  # - blueprint_fields
-  # - blueprint_setup
-  # - around_serialize_object | around_serialize_collection
-  #   - object_input | collection_input
-  #   - blueprint_input
-  #     - extract_value
-  #     - field_value | object_field_value | collection_field_value
-  #     - exclude_field? | exclude_object_field? | exclude_collection_field?
-  #       - blueprint_fields …
-  #     - field_result | object_field_result | collection_field_result
-  #   - blueprint_output
-  #   - object_output | collection_output
-  # - json
+  # - around_result
+  #   - around_blueprint_init
+  #     - around_serialize_object | around_serialize_collection
+  #       - around_blueprint
+  #         - around_field_value | around_object_value | around_collection_value
+  #           - around_blueprint_init …
   #
   # V1 hook call order:
   #  - pre_render
   #
   class Extension
+    include V2::Helpers
+
     HOOKS = %i[
       around_hook
-      blueprint
-      blueprint_fields
-      blueprint_setup
+      around_result
+      around_blueprint_init
       around_serialize_object
       around_serialize_collection
-      object_input
-      collection_input
-      blueprint_input
-      extract_value
-      field_value
-      exclude_field?
-      field_result
-      object_field_value
-      exclude_object_field?
-      object_field_result
-      collection_field_value
-      exclude_collection_field?
-      collection_field_result
-      blueprint_output
-      object_output
-      collection_output
-      json
+      around_blueprint
+      around_field_value
+      around_object_value
+      around_collection_value
       pre_render
     ].freeze
 
@@ -61,16 +41,23 @@ def self.hooks
     # If this returns true, around_hook will not be called when this extension's hooks are run. Used by core extensions.
     def hidden? = false
 
-    # around_serialize_object: Runs around serialization of a Blueprint object. Surrounds the `prepare` through
-    # `blueprint_output` hooks. MUST yield!
+    # around_result TODO
+    # @param context [Blueprinter::V2::Context::Result]
+
+    # around_serialize_object: Runs around serialization of a Blueprint object.
     # @param context [Blueprinter::V2::Context::Object]
 
-    # around_collection: Runs around serialization of a Blueprint collection. Surrounds the `prepare` through
-    # `blueprint_output` hooks. MUST yield!
+    # around_serialize_collection: Runs around serialization of a Blueprint collection.
     # @param context [Blueprinter::V2::Context::Object]
 
-    # blueprint: Returns the blueprint class to render with. The context's "fields" field will be empty.
-    # @param context [Blueprinter::V2::Context::Render]
+    # around_blueprint: Runs around serialization of every Blueprint.
+    # @param context [Blueprinter::V2::Context::Object]
+
+    # around_field_value TODO
+
+    # around_object_value TODO
+
+    # around_collection_value TODO
 
     # blueprint_fields: Returns the fields that should be included in the correct order. Default is all fields in the order
     # in which they were defined.
@@ -83,52 +70,6 @@ def hidden? = false
     # and cache them in context.data, so we don't have to recalculate them for every field.
     # @param context [Blueprinter::V2::Context::Render]
 
-    # blueprint_input: Modify or replace an object right before it's serialized by a Blueprint. The returned object will be
-    # used as the input to the Blueprint.
-    # @param context [Blueprinter::V2::Context::Object]
-    # @return [Object]
-
-    # blueprint_output: Modify or replace the serialized output from any Blueprint. The returned object will be used as the
-    # output of the Blueprint.
-    # @param context [Blueprinter::V2::Context::Result]
-    # @return [Object]
-
-    # extract_value: Extract a field, objecet, or collection value from an object. The returned value will be run through the
-    # NOTE If there are multiple extract_value hooks, only the last one is called.
-    # field_value, object_fled_value, or collection_fled_value hooks.
-
-    # field_value: Modify or replace the value used for the field. The returned value will be run through any formatters and
-    # used as the field's value.
-    # @param context [Blueprinter::V2::Context::Field]
-    # @return [Object]
-
-    # object_field_value: Modify or replace the value used for the object. The returned value will be used as the input for
-    # the object's Blueprint.
-    # @param context [Blueprinter::V2::Context::Field]
-    # @return [Object]
-
-    # collection_field_value: Modify or replace the value used for the collection. The returned value will be used as the
-    # input for the collection's Blueprint.
-    # @param context [Blueprinter::V2::Context::Field]
-    # @return [Enumerable]
-
-    # exclude_field?: Return true to exclude this field from the result.
-    # @param context [Blueprinter::V2::Context::Field]
-    # @return [Boolean]
-
-    # exclude_object_field?: Return true to exclude this object from the result.
-    # @param context [Blueprinter::V2::Context::Field]
-    # @return [Boolean]
-
-    # exclude_collection_field?: Return true to exclude this collection from the result.
-    # @param context [Blueprinter::V2::Context::Field]
-    # @return [Boolean]
-
-    # json: Override the default JSON encoder. The returned string will be the JSON output.
-    # NOTE If there are multiple json hooks, only the final one is called.
-    # @param context [Blueprinter::V2::Context::Result]
-    # @return [String]
-
     # around_hook: Instrument extension hook calls. MUST yield!
     # @param extension [Blueprinter::Extension] Instance of the extension
     # @param hook [Symbol] Name of hook being called
@@ -140,5 +81,13 @@ def hidden? = false
     # @param view [Symbol] The blueprint view
     # @param options [Hash] Options passed to "render"
     # @return [Object] The object to continue rendering
+
+    private
+
+    # Helper for around_result hooks to declare that a result is "final"
+    def final(val) = V2::Context::Final.new(val)
+
+    # Helper for around_result hooks to check if a previous hook has declared a result "final"
+    def final?(val) = val.is_a? V2::Context::Final
   end
 end

lib/blueprinter/extensions/field_order.rb

@@ -17,9 +17,9 @@ def initialize(&sorter)
       end
 
       # @param ctx [Blueprinter::V2::Context::Render]
-      # @return [Array<Blueprinter::V2::Fields::*>]
-      def blueprint_fields(ctx)
-        ctx.fields.sort(&@sorter)
+      def around_blueprint_init(ctx)
+        ctx.fields = ctx.fields.sort(&@sorter)
+        yield ctx
       end
     end
   end

lib/blueprinter/extensions/multi_json.rb

@@ -16,9 +16,16 @@ def initialize(options = {})
       end
 
       # @param ctx [Blueprinter::V2::Context::Result]
-      def json(ctx)
-        opts = ctx.options[:multi_json] ? @options.merge(ctx.options[:multi_json]) : @options
-        ::MultiJson.dump(ctx.result, opts)
+      def around_result(ctx)
+        case ctx.format
+        when :json
+          ctx.format = :hash
+          result = yield ctx
+          opts = ctx.options[:multi_json] ? @options.merge(ctx.options[:multi_json]) : @options
+          final ::MultiJson.dump(result, opts)
+        else
+          yield ctx
+        end
       end
     end
   end

lib/blueprinter/extensions/open_telemetry.rb

@@ -13,20 +13,24 @@ def initialize(tracer_name)
       end
 
       # @param ctx [Blueprinter::V2::Context::Object]
-      def around_serialize_object(ctx, &)
-        tracer.in_span('blueprinter.object', attributes: attributes(ctx), &)
+      def around_serialize_object(ctx)
+        tracer.in_span('blueprinter.object', attributes: attributes(ctx)) do
+          yield ctx
+        end
       end
 
       # @param ctx [Blueprinter::V2::Context::Object]
-      def around_serialize_collection(ctx, &)
-        tracer.in_span('blueprinter.collection', attributes: attributes(ctx), &)
+      def around_serialize_collection(ctx)
+        tracer.in_span('blueprinter.collection', attributes: attributes(ctx)) do
+          yield ctx
+        end
       end
 
       # @param ctx [Blueprinter::V2::Context::Hook]
-      def around_hook(ctx, &)
+      def around_hook(ctx)
         extension = ctx.extension.class.name
         attributes = { extension:, hook: ctx.hook, 'library.name' => 'Blueprinter', 'library.version' => VERSION }
-        tracer.in_span('blueprinter.extension', attributes:, &)
+        tracer.in_span('blueprinter.extension', attributes:) { |_| yield }
       end
 
       def hidden? = true

lib/blueprinter/extensions/view_option.rb

@@ -6,13 +6,13 @@ module Extensions
     # An optional, built-in extension for a ":view" option on render.
     #
     class ViewOption < Extension
-      # @param ctx [Blueprinter::V2::Context::Render]
-      def blueprint(ctx)
+      # @param ctx [Blueprinter::V2::Context::Result]
+      def around_result(ctx)
         if (view = ctx.options[:view])
-          ctx.blueprint.class[view]
-        else
-          ctx.blueprint.class
+          ctx.blueprint = ctx.blueprint.class[view].new
+          ctx.options = ctx.options.except(:view).freeze
         end
+        yield ctx
       end
 
       def hidden? = true

lib/blueprinter/extractors/association_extractor.rb

@@ -32,9 +32,10 @@ def extract(association_name, object, local_options, options = {})
 
     def extract_v2(value, blueprint, local_options, options)
       view = options[:view] || :default
+      store = local_options[:v2_store] || {}
       depth = local_options[:v2_depth] || 1
       instances = local_options[:v2_instances] || V2::InstanceCache.new
-      serializer = instances.serializer(blueprint[view], local_options.except(:v2_instances), depth + 1)
+      serializer = instances.serializer(blueprint[view], local_options.except(:v2_instances), store, depth + 1)
       if value.is_a?(Enumerable) && !value.is_a?(Hash)
         serializer.collection(value, depth: depth + 1)
       else