pakyow-support 0.11.3 → 1.0.0.rc1

data/lib/pakyow/support/makeable.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "pakyow/support/hookable"
+
+require "pakyow/support/makeable/object_maker"
+require "pakyow/support/makeable/object_name"
+
+module Pakyow
+  module Support
+    # @api private
+    module Makeable
+      def self.extended(base)
+        # Mixin the `make` event for objects that are hookable.
+        #
+        if base.ancestors.include?(Hookable)
+          base.events :make
+        end
+      end
+
+      attr_reader :__object_name
+
+      def make(object_name, within: nil, set_const: true, **kwargs, &block)
+        object_name = build_object_name(object_name, within: within)
+        object = find_or_define_object(object_name, kwargs, set_const)
+
+        local_eval_method = eval_method
+        object.send(eval_method) do
+          @__object_name = object_name
+          send(local_eval_method, &block) if block_given?
+        end
+
+        if object.ancestors.include?(Hookable)
+          object.call_hooks(:after, :make)
+        end
+
+        object
+      end
+
+      private
+
+      def build_object_name(object_name, within:)
+        unless object_name.is_a?(ObjectName) || object_name.nil?
+          namespace = if within && within.respond_to?(:__object_name)
+            within.__object_name.namespace
+          elsif within.is_a?(ObjectNamespace)
+            within
+          else
+            ObjectNamespace.new
+          end
+
+          object_name_parts = object_name.to_s.gsub("-", "_").split("/").reject(&:empty?)
+          class_name = object_name_parts.pop || :index
+
+          object_name = Support::ObjectName.new(
+            Support::ObjectNamespace.new(
+              *(namespace.parts + object_name_parts)
+            ), class_name
+          )
+        end
+
+        object_name
+      end
+
+      def find_or_define_object(object_name, kwargs, set_const)
+        if object_name && ::Object.const_defined?(object_name.constant, false)
+          existing_object = ::Object.const_get(object_name.constant)
+
+          if type_of_self?(existing_object)
+            existing_object
+          else
+            define_object(kwargs)
+          end
+        else
+          define_object(kwargs).tap do |defined_object|
+            if set_const
+              ObjectMaker.define_const_for_object_with_name(defined_object, object_name)
+            end
+          end
+        end
+      end
+
+      def type_of_self?(object)
+        object.ancestors.include?(ancestors[1])
+      end
+
+      def define_object(kwargs)
+        object = case self
+        when Class
+          Class.new(self)
+        when Module
+          Module.new do
+            def self.__object_name
+              @__object_name
+            end
+          end
+        end
+
+        object.send(eval_method) do
+          kwargs.each do |arg, value|
+            instance_variable_set(:"@#{arg}", value)
+          end
+        end
+
+        object
+      end
+
+      def eval_method
+        case self
+        when Class
+          :class_exec
+        when Module
+          :module_exec
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/message_verifier.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require "securerandom"
+
+module Pakyow
+  module Support
+    # Signs and verifes messages for a key.
+    #
+    class MessageVerifier
+      attr_reader :key
+
+      JOIN_CHARACTER = "--"
+
+      # TODO: support configuring the digest
+      # TODO: support rotations by calling `rotate` with options
+      #
+      def initialize(key = self.class.key)
+        @key = key
+      end
+
+      # Returns a signed message.
+      #
+      def sign(message)
+        [Base64.urlsafe_encode64(message), self.class.digest(message, key: @key)].join(JOIN_CHARACTER)
+      end
+
+      # Returns the message if the signature is valid for the key, or raises `TamperedMessage`.
+      #
+      def verify(signed)
+        message, digest = signed.to_s.split(JOIN_CHARACTER, 2)
+
+        begin
+          message = Base64.urlsafe_decode64(message.to_s)
+        rescue ArgumentError
+        end
+
+        if self.class.valid?(digest, message: message, key: @key)
+          message
+        else
+          raise(TamperedMessage)
+        end
+      end
+
+      class << self
+        # Generates a random key.
+        #
+        def key
+          SecureRandom.hex(24)
+        end
+
+        # Generates a digest for a message with a key.
+        #
+        def digest(message, key:)
+          Base64.urlsafe_encode64(
+            OpenSSL::HMAC.digest(
+              OpenSSL::Digest.new("sha256"), message.to_s, key.to_s
+            )
+          )
+        end
+
+        # Returns true if the digest is valid for the message and key.
+        #
+        def valid?(digest, message:, key:)
+          digest == self.digest(message, key: key)
+        end
+      end
+
+      class TamperedMessage < StandardError
+      end
+    end
+  end
+end

data/lib/pakyow/support/path_version.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+module Pakyow
+  module Support
+    class PathVersion
+      # Builds a version based on content at local paths.
+      #
+      def self.build(*paths)
+        paths.each_with_object(Digest::SHA1.new) { |path, digest|
+          Dir.glob(File.join(path, "/**/*")).sort.each do |fullpath|
+            if File.file?(fullpath)
+              digest.update(Digest::SHA1.file(fullpath).to_s)
+            end
+          end
+        }.to_s
+      end
+    end
+  end
+end

data/lib/pakyow/support/pipeline/object.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Support
+    module Pipeline
+      # Makes an object passable through a pipeline.
+      #
+      module Object
+        def self.included(base)
+          base.prepend Initializer
+        end
+
+        def pipelined
+          tap do
+            @pipelined = true
+          end
+        end
+
+        def pipelined?
+          @pipelined == true
+        end
+
+        def halt
+          @halted = true
+          throw :halt, true
+        end
+
+        def halted?
+          @halted == true
+        end
+
+        module Initializer
+          def initialize(*args)
+            @pipelined, @halted = false
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/pipeline.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require "pakyow/support/class_state"
+
+module Pakyow
+  module Support
+    # Provides pipeline behavior. Pipeline objects can define actions to be called in order on an
+    # instance of the pipelined object. Each action can act on the state passed to it. Any action
+    # can halt the pipeline, causing the result to be immediately returned without calling other
+    # actions. State passed through the pipeline should include {Pipelined::Object}.
+    #
+    # See {Pakyow::App} and {Pakyow::Controller} for examples of more complex pipelines.
+    #
+    # @example
+    #   class App
+    #     include Pakyow::Support::Pipeline
+    #
+    #     action :foo
+    #     action :bar
+    #
+    #     def foo(result)
+    #       result << "foo"
+    #     end
+    #
+    #     def bar(result)
+    #       result << "bar"
+    #     end
+    #   end
+    #
+    #   class Result
+    #     include Pakyow::Support::Pipeline::Object
+    #
+    #     attr_reader :results
+    #
+    #     def initialize
+    #       @results = []
+    #     end
+    #
+    #     def <<(result)
+    #       @results << result
+    #     end
+    #   end
+    #
+    #   App.new.call(Result.new).results
+    #   => ["foo", "bar"]
+    #
+    # = Modules
+    #
+    # Pipeline behavior can be added to a module and then used in a pipelined object.
+    #
+    # @example
+    #   module VerifyRequest
+    #     extend Pakyow::Support::Pipeline
+    #
+    #     action :verify_request
+    #
+    #     def verify_request
+    #       ...
+    #     end
+    #   end
+    #
+    #   class App
+    #     include Pakyow::Support::Pipeline
+    #
+    #     use_pipeline VerifyRequest
+    #
+    #     ...
+    #   end
+    #
+    module Pipeline
+      # @api private
+      def self.extended(base)
+        base.extend ClassMethods
+        base.extend ClassState unless base.ancestors.include?(ClassState)
+        base.class_state :__pipelines, default: {}, inheritable: true
+        base.class_state :__pipeline, inheritable: true
+
+        base.instance_variable_set(:@__pipeline, Internal.new)
+      end
+
+      # @api private
+      def self.included(base)
+        base.extend ClassMethods
+        base.extend ClassState unless base.ancestors.include?(ClassState)
+        base.prepend Initializer
+        base.class_state :__pipelines, default: {}, inheritable: true
+        base.class_state :__pipeline, inheritable: true
+
+        # Define a default pipeline so that actions can be defined immediately without ceremony.
+        #
+        base.pipeline :default do; end
+        base.use_pipeline :default
+      end
+
+      # Calls the pipeline, passing +state+.
+      #
+      def call(state)
+        @__pipeline.call(state)
+      end
+
+      def initialize_copy(_)
+        super
+
+        @__pipeline = @__pipeline.dup
+
+        # rebind any methods to the new instance
+        @__pipeline.instance_variable_get(:@stack).map! { |action|
+          if action.is_a?(::Method) && action.receiver.is_a?(self.class)
+            action.unbind.bind(self)
+          else
+            action
+          end
+        }
+      end
+
+      # @api private
+      module Initializer
+        def initialize(*)
+          @__pipeline = self.class.__pipeline.callable(self)
+          super
+        end
+      end
+
+      module ClassMethods
+        # Defines a pipeline.
+        #
+        def pipeline(name, &block)
+          @__pipelines[name.to_sym] = Internal.new(&block)
+        end
+
+        # Uses a pipeline.
+        #
+        def use_pipeline(name_or_pipeline)
+          pipeline = find_pipeline(name_or_pipeline)
+          include name_or_pipeline if name_or_pipeline.is_a?(Pipeline)
+          @__pipeline = pipeline
+        end
+
+        # Includes actions into the current pipeline.
+        #
+        def include_pipeline(name_or_pipeline)
+          pipeline = find_pipeline(name_or_pipeline)
+          include name_or_pipeline if name_or_pipeline.is_a?(Pipeline)
+          @__pipeline.include_actions(pipeline.actions)
+        end
+
+        # Excludes actions from the current pipeline.
+        #
+        def exclude_pipeline(name_or_pipeline)
+          pipeline = find_pipeline(name_or_pipeline)
+          @__pipeline.exclude_actions(pipeline.actions)
+        end
+
+        # Defines an action on the current pipeline.
+        #
+        def action(action = nil, *options, before: nil, after: nil, &block)
+          @__pipeline.action(action, *options, before: before, after: after, &block)
+        end
+
+        def skip(*actions)
+          @__pipeline.skip(*actions)
+        end
+
+        private
+
+        def find_pipeline(name_or_pipeline)
+          if name_or_pipeline.is_a?(Pipeline)
+            name_or_pipeline.instance_variable_get(:@__pipeline)
+          elsif name_or_pipeline.is_a?(Internal)
+            name_or_pipeline
+          else
+            name_or_pipeline = name_or_pipeline.to_sym
+            if @__pipelines.key?(name_or_pipeline)
+              @__pipelines[name_or_pipeline]
+            else
+              raise ArgumentError, "could not find a pipeline named `#{name_or_pipeline}'"
+            end
+          end
+        end
+      end
+
+      # @api private
+      class Internal
+        attr_reader :actions
+
+        def initialize
+          @actions = []
+
+          if block_given?
+            instance_exec(&Proc.new)
+          end
+        end
+
+        def initialize_copy(_)
+          @actions = @actions.dup
+          super
+        end
+
+        def callable(context)
+          Callable.new(@actions, context)
+        end
+
+        def action(target, *options, before: nil, after: nil, &block)
+          Action.new(target, *options, &block).tap do |action|
+            if before
+              if i = @actions.index { |a| a.name == before }
+                @actions.insert(i, action)
+              else
+                @actions.unshift(action)
+              end
+            elsif after
+              if i = @actions.index { |a| a.name == after }
+                @actions.insert(i + 1, action)
+              else
+                @actions << action
+              end
+            else
+              @actions << action
+            end
+          end
+        end
+
+        def skip(*actions)
+          @actions.delete_if { |action|
+            actions.include?(action.name)
+          }
+        end
+
+        def include_actions(actions)
+          @actions.concat(actions).uniq!
+        end
+
+        def exclude_actions(actions)
+          # Map input into a common denominator, to exclude both names and other action objects.
+          targets = actions.map { |action|
+            if action.is_a?(Action)
+              action.target
+            else
+              action
+            end
+          }
+
+          @actions.delete_if { |action|
+            targets.include?(action.target)
+          }
+        end
+      end
+
+      # @api private
+      class Callable
+        def initialize(actions, context)
+          @stack = actions.map { |action|
+            action.finalize(context)
+          }
+        end
+
+        def initialize_copy(_)
+          @stack = @stack.dup
+
+          super
+        end
+
+        def call(object, stack = @stack.dup)
+          catch :halt do
+            until stack.empty? || (object.respond_to?(:halted?) && object.halted?)
+              action = stack.shift
+              if action.arity == 0
+                action.call do
+                  call(object, stack)
+                end
+              else
+                action.call(object) do
+                  call(object, stack)
+                end
+              end
+            end
+          end
+
+          object.pipelined
+        end
+      end
+
+      # @api private
+      class Action
+        attr_reader :target, :name, :options
+
+        def initialize(target, *options, &block)
+          @target, @options, @block = target, options, block
+
+          if target.is_a?(Symbol)
+            @name = target
+          end
+        end
+
+        def finalize(context = nil)
+          if @block
+            if context
+              if @block.arity == 0
+                Proc.new do
+                  context.instance_exec(&@block)
+                end
+              else
+                Proc.new do |object|
+                  context.instance_exec(object, &@block)
+                end
+              end
+            else
+              @block
+            end
+          elsif @target.is_a?(Symbol) && context.respond_to?(@target, true)
+            if context
+              context.method(@target)
+            else
+              raise "finalizing pipeline action #{@target} requires context"
+            end
+          else
+            target, target_options = if @target.is_a?(Symbol)
+              [@options[0], @options[1..-1]]
+            else
+              [@target, @options]
+            end
+
+            instance = if target.is_a?(Class)
+              target.new(*target_options)
+            else
+              target
+            end
+
+            instance.method(:call)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/safe_string.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Pakyow
+  module Support
+    class SafeString < String
+      def initialize(*)
+        super; freeze
+      end
+
+      def to_s
+        self
+      end
+    end
+
+    # Helper methods for ensuring string safety.
+    #
+    module SafeStringHelpers
+      extend self
+
+      # Escapes the string unless it's marked as safe.
+      #
+      def ensure_html_safety(string)
+        html_safe?(string) ? string : html_escape(string)
+      end
+
+      # Returns true if the string is marked as safe.
+      #
+      def html_safe?(string)
+        string.is_a?(SafeString)
+      end
+
+      # Marks a string as safe.
+      #
+      def html_safe(string)
+        html_safe?(string) ? string : SafeString.new(string)
+      end
+
+      # Escapes html characters in the string.
+      #
+      def html_escape(string)
+        html_safe(CGI.escape_html(string.to_s))
+      end
+
+      # Strips html tags from the string.
+      #
+      def strip_tags(string)
+        html_safe(string.to_s.gsub(/<[^>]*>/ui, ""))
+      end
+
+      # Strips html tags from the string, except for tags specified.
+      #
+      def sanitize(string, tags: [])
+        return strip_tags(string) if tags.empty?
+        html_safe(string.to_s.gsub(/((?!<((\/)?#{tags.join("|")}))<[^>]*>)/i, ""))
+      end
+    end
+  end
+end

data/lib/pakyow/support/serializer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+require "pakyow/support/logging"
+
+module Pakyow
+  module Support
+    # Persists state for an object.
+    #
+    class Serializer
+      attr_reader :object, :name, :path
+
+      def initialize(object, name:, path:)
+        @object, @name, @path = object, name, path
+      end
+
+      def serialize
+        FileUtils.mkdir_p(@path)
+        File.open(serialized_state_path, "w+") do |file|
+          file.write(Marshal.dump(@object.serialize))
+        end
+      rescue => error
+        Logging.yield_or_raise(error) do |logger|
+          logger.error "[Serializer] failed to serialize `#{@name}': #{error}"
+        end
+      end
+
+      def deserialize
+        if File.exist?(serialized_state_path)
+          Marshal.load(File.read(serialized_state_path)).each do |ivar, value|
+            @object.instance_variable_set(ivar, value)
+          end
+        end
+      rescue => error
+        FileUtils.rm(serialized_state_path)
+        Logging.yield_or_raise(error) do |logger|
+          logger.error "[Serializer] failed to deserialize `#{@name}': #{error}"
+        end
+      end
+
+      private
+
+      def serialized_state_path
+        File.join(@path, "#{@name}.pwstate")
+      end
+    end
+  end
+end