panko_serializer 0.8.5 → 1.0.0

data/lib/panko/config.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Panko
+  # Process-global settings, read at serialize time. Set them in an
+  # initializer, before serializers compile:
+  #
+  #   Panko.configure do |config|
+  #     config.auto_specialization.capacity = 32
+  #   end
+  class Config
+    # The engine compiles a specialized Generated Class for each named
+    # ActiveRecord class a serializer sees, up to +capacity+.
+    class AutoSpecialization
+      # @return [Boolean] +false+ routes every record class to the generic path
+      attr_reader :enabled
+
+      # @return [Integer] max specialized variants per serializer class and output
+      #   mode; past it, record classes use the generic path, with one warning
+      #   per serializer class
+      attr_reader :capacity
+
+      def initialize
+        @enabled = true
+        @capacity = 16
+      end
+
+      def enabled=(value)
+        unless value.equal?(true) || value.equal?(false)
+          raise ArgumentError,
+            "auto_specialization.enabled: must be true or false; got #{value.inspect}:#{value.class}"
+        end
+        @enabled = value
+      end
+
+      def capacity=(value)
+        unless value.is_a?(Integer) && value.positive?
+          raise ArgumentError,
+            "auto_specialization.capacity: must be a positive Integer; got #{value.inspect}:#{value.class}"
+        end
+        @capacity = value
+      end
+    end
+
+    @auto_specialization = AutoSpecialization.new
+    @writer_pool_max_bytes = 1_048_576
+
+    class << self
+      attr_reader :auto_specialization
+
+      # Largest +serialize_to_json+ output, in bytes, whose writer goes back to
+      # the pool. +Oj::StringWriter#reset+ keeps the grown buffer, so a larger
+      # writer is dropped instead of holding that memory. Read on every checkin.
+      #
+      # @return [Integer] default 1_048_576 (1 MB)
+      attr_reader :writer_pool_max_bytes
+
+      def writer_pool_max_bytes=(value)
+        unless value.is_a?(Integer) && value.positive?
+          raise ArgumentError,
+            "writer_pool_max_bytes: must be a positive Integer; got #{value.inspect}:#{value.class}"
+        end
+        @writer_pool_max_bytes = value
+      end
+    end
+  end
+
+  # Yields the {Config} class for block-style configuration.
+  def self.configure
+    yield Config
+  end
+end

data/lib/panko/descriptor.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "code_gen/serializer_cache"
+
+module Panko
+  # Public, read-only view of a serializer's shape, for tools like association
+  # preloaders. Separate from Panko::CodeGen::Descriptor so the engine can change.
+  class Descriptor
+    Attribute = Data.define(:name, :source)
+    MethodAttribute = Data.define(:name, :source)
+    Association = Data.define(:name, :source, :kind, :descriptor)
+
+    attr_reader :serializer, :attributes, :method_attributes, :associations
+
+    # Cached on the serializer class. A concurrent first build is harmless:
+    # both threads build frozen views with the same content.
+    def self.for(serializer_class)
+      serializer_class._cg_public_descriptor ||= wrap(
+        CodeGen::SerializerCache.descriptor_for(serializer_class)
+      )
+    end
+
+    def self.wrap(internal)
+      new(
+        serializer: internal.parent_class,
+        attributes: internal.attributes.map { |a| Attribute.new(name: a.name, source: a.source) }.freeze,
+        method_attributes: internal.method_attributes.map { |m| wrap_method_attribute(m) }.freeze,
+        associations: internal.associations.map do |as|
+          Association.new(name: as.name, source: as.source, kind: as.kind, descriptor: wrap(as.descriptor))
+        end.freeze
+      ).freeze
+    end
+    private_class_method :wrap
+
+    # A Callable body has no method name, so +source+ is nil. The DSL only
+    # makes Symbol bodies.
+    def self.wrap_method_attribute(method_attribute)
+      body = method_attribute.body
+      MethodAttribute.new(name: method_attribute.name, source: body.is_a?(Symbol) ? body : nil)
+    end
+    private_class_method :wrap_method_attribute
+
+    def initialize(serializer:, attributes:, method_attributes:, associations:)
+      @serializer = serializer
+      @attributes = attributes
+      @method_attributes = method_attributes
+      @associations = associations
+    end
+
+    # Resolves each level on first read and memoizes it, so only the levels a
+    # caller visits cost anything. +filters+ has the shape
+    # Panko::CodeGen::Runtime.runtime_filters returns.
+    class Filtered < Descriptor
+      def initialize(skeleton, filters)
+        @skeleton = skeleton
+        @filters = filters
+      end
+
+      def serializer
+        @skeleton.serializer
+      end
+
+      def attributes
+        @attributes ||= @skeleton.attributes.select { |a| keep?(a.name) }.freeze
+      end
+
+      def method_attributes
+        @method_attributes ||= @skeleton.method_attributes.select { |m| keep?(m.name) }.freeze
+      end
+
+      # Associations are filtered by +source+, the declared relation name, as
+      # the serialize path does.
+      def associations
+        @associations ||= @skeleton.associations.filter_map do |as|
+          next unless keep?(as.source)
+          sub = @filters[as.source]
+          (sub.is_a?(Hash) && !sub.empty?) ? as.with(descriptor: Filtered.new(as.descriptor, sub)) : as
+        end.freeze
+      end
+
+      private
+
+      # FilterAdapter never emits both :only and :except at one level.
+      def keep?(name)
+        only = @filters[:only]
+        return only.include?(name) unless only.nil?
+        except = @filters[:except]
+        return !except.include?(name) unless except.nil?
+        true
+      end
+    end
+  end
+end

data/lib/panko/response.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "oj"
+require_relative "code_gen/writers_pool"
 
 module Panko
   JsonValue = Struct.new(:value) do
@@ -13,6 +14,17 @@ module Panko
     end
   end
 
+  # A serializer and the object it serializes, written straight into the Response writer.
+  SerializerValue = Struct.new(:serializer, :object) do
+    def to_json
+      serializer.serialize_to_json(object)
+    end
+
+    def write_json(writer, key = nil)
+      serializer.write_json(object, writer, key)
+    end
+  end
+
   class ResponseCreator
     def self.value(value)
       Panko::Response.new(value)
@@ -28,19 +40,39 @@ module Panko
     end
 
     def self.serializer(data, serializer, options = {})
-      json serializer.new(options).serialize_to_json(data)
+      Panko::SerializerValue.new(serializer.new(options), data)
     end
   end
 
   class Response
+    # Picked on first use, like the generated classes' pools, so an app that loads
+    # ActiveSupport after Panko still shares one writer stack with them.
+    def self.writers
+      @writers ||= defined?(ActiveSupport::IsolatedExecutionState) ?
+        Panko::CodeGen::WritersPool::IsolatedExecutionState.new :
+        Panko::CodeGen::WritersPool::ThreadLocal.new
+    end
+
     def initialize(data)
       @data = data
     end
 
     def to_json(_options = nil)
-      writer = Oj::StringWriter.new(mode: :rails)
-      write(writer, @data)
-      writer.to_s
+      writers = Response.writers
+      writer = writers.checkout
+      result = nil
+      begin
+        write(writer, @data)
+        result = writer.to_s
+      ensure
+        writers.checkin(writer, result)
+      end
+    end
+
+    # Writes this Response into +writer+ as the value of +key+, or as the next element when
+    # +key+ is nil.
+    def write_json(writer, key = nil)
+      write(writer, @data, key)
     end
 
     def self.create
@@ -74,10 +106,10 @@ module Panko
     end
 
     def write_value(writer, value, key = nil)
-      if value.is_a?(Panko::ArraySerializer) ||
-          value.is_a?(Panko::Serializer) ||
-          value.is_a?(Panko::Response) ||
-          value.is_a?(Panko::JsonValue)
+      case value
+      when Panko::ArraySerializer, Panko::Response, Panko::SerializerValue
+        value.write_json(writer, key)
+      when Panko::Serializer, Panko::JsonValue
         writer.push_json(value.to_json, key)
       else
         writer.push_value(value, key)

data/lib/panko/serializer.rb

@@ -1,146 +1,230 @@
 # frozen_string_literal: true
 
-require_relative "serialization_descriptor"
+require_relative "code_gen"
+require_relative "code_gen/descriptor_builder"
+require_relative "code_gen/runtime"
 require "oj"
 
-class SerializationContext
-  attr_accessor :context, :scope
+module Panko
+  class Serializer
+    # A method field that returns SKIP leaves its key out of the output.
+    SKIP = Panko::CodeGen::SKIP
 
-  def initialize(context, scope)
-    @context = context
-    @scope = scope
-  end
+    EMPTY_MODELS = [].freeze
 
-  def self.create(options)
-    if options.key?(:context) || options.key?(:scope)
-      SerializationContext.new(options[:context], options[:scope])
-    else
-      EmptySerializerContext.new
-    end
-  end
-end
+    class << self
+      attr_accessor :_cg_attributes, :_cg_method_attributes, :_cg_associations
 
-class EmptySerializerContext
-  def scope
-    nil
-  end
+      # Not copied on inheritance: each class compiles its own.
+      attr_accessor :_cg_state
 
-  def context
-    nil
-  end
-end
+      # One-entry inline caches: frozen [model, pool] pairs.
+      attr_accessor :_cg_last_json, :_cg_last_hash
 
-module Panko
-  class Serializer
-    SKIP = Object.new.freeze
+      attr_accessor :_cg_public_descriptor
 
-    class << self
-      def inherited(base)
-        if _descriptor.nil?
-          base._descriptor = Panko::SerializationDescriptor.new
+      # Lets the unfiltered hot path skip filter resolution. A stale +true+ only
+      # costs a +respond_to?+ inside +runtime_filters+.
+      attr_accessor :_cg_has_filters_for
 
-          base._descriptor.attributes = []
-          base._descriptor.aliases = {}
+      attr_accessor :_cg_models
 
-          base._descriptor.method_fields = []
+      def inherited(base)
+        base._cg_attributes = (_cg_attributes || []).dup
+        base._cg_method_attributes = (_cg_method_attributes || []).dup
+        base._cg_associations = (_cg_associations || []).dup
+        base._cg_has_filters_for = base.respond_to?(:filters_for)
+        base._cg_models = _cg_models || EMPTY_MODELS
+      end
 
-          base._descriptor.has_many_associations = []
-          base._descriptor.has_one_associations = []
-        else
-          base._descriptor = Panko::SerializationDescriptor.duplicate(_descriptor)
-        end
-        base._descriptor.type = base
+      # Declares the record classes this serializer expects, so Panko.compile_all
+      # can compile a specialized variant for each at boot. A hint only: records
+      # of other classes still serialize. Subclasses inherit the list; a second
+      # call replaces it.
+      #
+      # @param models [Array<Class>]
+      # @raise [ArgumentError] when an argument is not a Class
+      def models(*models)
+        invalid = models.reject { |model| model.is_a?(Class) }
+        raise ArgumentError, "models: expected classes, got #{invalid.inspect}" unless invalid.empty?
+        self._cg_models = models.freeze
       end
 
-      attr_accessor :_descriptor
+      # A +filters_for+ defined or stubbed after the first serialize must still apply.
+      def singleton_method_added(method)
+        super
+        @_cg_has_filters_for = true if method == :filters_for
+      end
 
       def attributes(*attrs)
-        @_descriptor.attributes.push(*attrs.map { |attr| Attribute.create(attr) }).uniq!
+        attrs.each { |attr| add_attribute(attr.to_sym, attr.to_sym) }
       end
 
       def aliases(aliases = {})
-        aliases.each do |attr, alias_name|
-          @_descriptor.attributes << Attribute.create(attr, alias_name: alias_name)
-        end
+        aliases.each { |source, output| add_attribute(source.to_sym, output.to_sym) }
       end
 
+      # A method named like a declared attribute turns that attribute into a
+      # method field with the same output key.
       def method_added(method)
         super
+        return if _cg_attributes.nil?
+        index = _cg_attributes.index { |attribute| attribute.source == method }
+        return if index.nil?
+        attribute = _cg_attributes.delete_at(index)
+        _cg_method_attributes << Panko::CodeGen::MethodAttribute.new(name: attribute.name, body: method)
+      end
 
-        return if @_descriptor.nil?
-
-        deleted_attr = @_descriptor.attributes.delete(method)
-        @_descriptor.method_fields << Attribute.create(deleted_attr.name, alias_name: deleted_attr.alias_name) unless deleted_attr.nil?
+      # The static public view of this serializer's declared shape.
+      def descriptor
+        Panko::Descriptor.for(self)
       end
 
       def has_one(name, options = {})
-        serializer_const = options[:serializer]
-        if serializer_const.is_a?(String)
-          serializer_const = Panko::SerializerResolver.resolve(serializer_const, self)
-        end
-        serializer_const ||= Panko::SerializerResolver.resolve(name.to_s, self)
+        add_association(:has_one, name, options)
+      end
+
+      def has_many(name, options = {})
+        add_association(:has_many, name, options)
+      end
+
+      private
 
-        raise "Can't find serializer for #{self.name}.#{name} has_one relationship." if serializer_const.nil?
+      def add_attribute(source, output)
+        return if _cg_attributes.any? { |attribute| attribute.source == source }
+        _cg_attributes << Panko::CodeGen::Attribute.new(name: output, source: source)
+      end
 
-        @_descriptor.has_one_associations << Panko::Association.new(
-          name,
-          options.fetch(:name, name).to_s,
-          Panko::SerializationDescriptor.build(serializer_const, options)
+      def add_association(kind, name, options)
+        serializer = resolve_association_serializer(name, options, kind)
+        descriptor = Panko::CodeGen::DescriptorBuilder.build(serializer)
+        only, except = association_filters(serializer, options)
+        descriptor = Panko::CodeGen::DescriptorBuilder.narrow(descriptor, only, except)
+        _cg_associations << Panko::CodeGen::Association.new(
+          name: options.fetch(:name, name).to_s.to_sym,
+          kind: kind,
+          descriptor: descriptor,
+          source: name.to_sym
         )
       end
 
-      def has_many(name, options = {})
-        serializer_const = options[:serializer] || options[:each_serializer]
-        if serializer_const.is_a?(String)
-          serializer_const = Panko::SerializerResolver.resolve(serializer_const, self)
+      # The nested serializer's +filters_for+ runs once, at declaration, with nil
+      # context and scope. Its keys win over the declared +only:+/+except:+.
+      def association_filters(serializer, options)
+        only = options[:only]
+        except = options[:except]
+
+        if serializer.respond_to?(:filters_for)
+          filters = serializer.filters_for(nil, nil)
+          only = filters[:only] if filters.key?(:only)
+          except = filters[:except] if filters.key?(:except)
         end
-        serializer_const ||= Panko::SerializerResolver.resolve(name.to_s, self)
 
-        raise "Can't find serializer for #{self.name}.#{name} has_many relationship." if serializer_const.nil?
+        [only, except]
+      end
 
-        @_descriptor.has_many_associations << Panko::Association.new(
-          name,
-          options.fetch(:name, name).to_s,
-          Panko::SerializationDescriptor.build(serializer_const, options)
-        )
+      def resolve_association_serializer(name, options, kind)
+        serializer = options[:serializer] || options[:each_serializer]
+        serializer = Panko::SerializerResolver.resolve(serializer, self) if serializer.is_a?(String)
+        serializer ||= Panko::SerializerResolver.resolve(name.to_s, self)
+        raise "Can't find serializer for #{self.name}.#{name} #{kind} relationship." if serializer.nil?
+        serializer
       end
     end
 
-    def initialize(options = {})
-      # this "_skip_init" trick is so I can create serializers from serialization descriptor
-      return if options[:_skip_init]
+    # A literal +{}+ default would allocate a Hash on every +.new+.
+    EMPTY_OPTIONS = {}.freeze
 
-      @serialization_context = SerializationContext.create(options)
-      @descriptor = Panko::SerializationDescriptor.build(self.class, options, @serialization_context)
-      @used = false
-    end
+    def initialize(options = EMPTY_OPTIONS)
+      # Unset ivars read as nil, so +.new+ skips four Hash lookups and four writes.
+      return if options.equal?(EMPTY_OPTIONS)
 
-    def context
-      @serialization_context.context
+      @context = options[:context]
+      @scope = options[:scope]
+      @only = options[:only]
+      @except = options[:except]
     end
 
-    def scope
-      @serialization_context.scope
+    # Generated code sets these per record on the instance a method field runs on.
+    attr_reader :object, :context, :scope
+
+    # The class-level view, narrowed by this instance's +only+/+except+ and +filters_for+.
+    def descriptor
+      klass = self.class
+      filters = if @only || @except || klass._cg_has_filters_for
+        Panko::CodeGen::Runtime.runtime_filters(klass, @context, @scope, @only, @except)
+      end
+      base = Panko::Descriptor.for(klass)
+      filters ? Panko::Descriptor::Filtered.new(base, filters) : base
     end
 
-    attr_writer :serialization_context
-    attr_reader :object
+    # Both methods inline the pool checkout instead of calling a shared Runtime
+    # method, which would go polymorphic once an app has more than one serializer.
 
     def serialize(object)
-      serialize_with_writer(object, Panko::ObjectWriter.new).output
+      klass = self.class
+      cached = klass._cg_last_hash
+      pool = if cached && object.instance_of?(cached[0])
+        cached[1]
+      else
+        Panko::CodeGen::SerializerCache.variant_pool(klass, :hash, object.class)
+      end
+      filters = if @only || @except || klass._cg_has_filters_for
+        Panko::CodeGen::Runtime.runtime_filters(klass, @context, @scope, @only, @except)
+      end
+      stack = pool.stack
+      instance = stack.pop || pool.build
+      begin
+        instance.serialize_one(object, context: @context, scope: @scope, filters: filters)
+      ensure
+        # A pooled instance must not hold the last record or request context.
+        instance._release
+        stack.push(instance)
+      end
     end
 
     def serialize_to_json(object)
-      serialize_with_writer(object, Oj::StringWriter.new(mode: :rails)).to_s
+      klass = self.class
+      cached = klass._cg_last_json
+      pool = if cached && object.instance_of?(cached[0])
+        cached[1]
+      else
+        Panko::CodeGen::SerializerCache.variant_pool(klass, :json, object.class)
+      end
+      filters = if @only || @except || klass._cg_has_filters_for
+        Panko::CodeGen::Runtime.runtime_filters(klass, @context, @scope, @only, @except)
+      end
+      stack = pool.stack
+      instance = stack.pop || pool.build
+      begin
+        instance.serialize_one(object, context: @context, scope: @scope, filters: filters)
+      ensure
+        instance._release
+        stack.push(instance)
+      end
     end
 
-    private
-
-    def serialize_with_writer(object, writer)
-      raise ArgumentError.new("Panko::Serializer instances are single-use") if @used
-      Panko.serialize_object(object, writer, @descriptor)
-      @used = true
-      writer
+    # Writes +object+ into +writer+ (an +Oj::StringWriter+) as the value of +key+, or as the
+    # next element when +key+ is nil. The bytes match what +serialize_to_json+ returns.
+    def write_json(object, writer, key = nil)
+      klass = self.class
+      cached = klass._cg_last_json
+      pool = if cached && object.instance_of?(cached[0])
+        cached[1]
+      else
+        Panko::CodeGen::SerializerCache.variant_pool(klass, :json, object.class)
+      end
+      filters = if @only || @except || klass._cg_has_filters_for
+        Panko::CodeGen::Runtime.runtime_filters(klass, @context, @scope, @only, @except)
+      end
+      stack = pool.stack
+      instance = stack.pop || pool.build
+      begin
+        instance.serialize_one_to(writer, object, key, context: @context, scope: @scope, filters: filters)
+      ensure
+        instance._release
+        stack.push(instance)
+      end
     end
   end
 end

data/lib/panko/serializer_resolver.rb

@@ -21,14 +21,8 @@ class Panko::SerializerResolver
 
     private
 
-    if Module.method_defined?(:module_parent_name)
-      def namespace_for(from)
-        from.module_parent_name
-      end
-    else
-      def namespace_for(from)
-        from.parent_name
-      end
+    def namespace_for(from)
+      from.module_parent_name
     end
 
     def safe_serializer_get(name)

data/lib/panko/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Panko
-  VERSION = "0.8.5"
+  VERSION = "1.0.0"
 end

data/lib/panko_serializer.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
 require "panko/version"
-require "panko/attribute"
-require "panko/association"
+require "panko/config"
 require "panko/serializer"
+require "panko/compile_all"
+require "panko/descriptor"
 require "panko/array_serializer"
 require "panko/response"
 require "panko/serializer_resolver"
-require "panko/object_writer"
 
-# C Extension
 require "oj"
-require "panko/panko_serializer"