dynamic_paperclip 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Room 118 Solutions, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,150 @@
+Dynamic Paperclip
+=================
+
+Dynamic Paperclip is an extension to the wonderful [Paperclip](http://github.com/thoughtbot/paperclip) gem
+and a Ruby on Rails engine that allows for the creation of Paperclip attachment styles on-the-fly.
+
+Instead of defining your attachment styles in your model, Dynamic Paperclip allows you to generate URL's
+for arbitrary attachment styles (usually in your view), effectively pushing style definition there.
+When the browser requests that asset, if it has not already been processed, it is then processed on-the-fly
+and sent back to the browser. If the style has already been processed, it's served just like any other static asset.
+
+Getting started
+---------------
+
+### Requirements
+
+Dynamic Paperclip requires Paperclip 3.5.0 or above and Rails 3.2.0 or above (although it may work on earlier versions,
+it's just untested at the moment).
+
+It also only currently supports Paperclip's File Storage.
+
+### Application
+
+Add the gem to your gemfile:
+
+```ruby
+gem 'dynamic_paperclip'
+```
+
+Run the ``bundle`` command to install it.
+
+After you install the gem, you need to run the generator:
+
+```console
+rails generate dynamic_paperclip:install
+```
+
+This will install an initializer that sets up a secret key used in validating that dynamic asset URL's
+originated from your application.
+
+Now, you're ready to start using Dynamic Paperclip. Change any attachment definitions that you'd like to make dynamic from:
+
+```ruby
+has_attached_file :avatar
+```
+
+To:
+
+```ruby
+has_dynamic_attached_file :avatar
+```
+
+You can continue defining styles there, too, you don't need to move over entirely to dynamic styles. You can have both!
+
+Then, whenever you'd like a URL to a dynamic style, simply call ``#dynamic_url`` instead of ``#url`` on the attachment,
+passing it the style definition that you would normally define in the ``:styles`` hash on ``has_attached_file``:
+
+```ruby
+@user.avatar.dynamic_url('100x100#')
+```
+
+### Server Configuration
+
+If you're using Rails to serve static assets, then no configuration is required.  But if you're not,
+which you shouldn't be in any production environment, then you just need to make sure that your HTTP server
+is configured to serve static assets if they exist, but pass the request along to your Rails application
+if they do not.
+
+For example, on Nginx, this would be accomplished with something along the lines of:
+
+```nginx
+upstream rails {
+  # ...
+}
+
+server {
+  # ...
+
+  try_files $uri @rails
+
+  location @rails {
+    # ...
+
+    proxy_pass  http://rails;
+  }
+}
+```
+
+This basically says "If the requested URI exists, send that to the browser, if not, pass it along to the Rails app.",
+and is a pretty standard Nginx setup.
+
+Why?
+----
+
+Because as your Rails application grows, you may discover that you have a large number of attachment styles.  This is
+slowing down your requests, because every time a user attempts to upload a file, Paperclip must process each and every
+one of those styles right then and there, in the middle of the request.
+
+Also, when dealing with images, I think it makes more sense to specify the dimensions of a thumbnail in the view
+that needs it, and not in the model.
+
+How does this wizardry work?
+---------------------------
+
+It's pretty simple, actually.  When you define a dynamic attachment on your model, Dynamic Paperclip defines
+a route in your application that routes the URL you've specified (or Paperclip's default) to the ``DynamicPaperclip::AttachmentStylesController``.
+
+For security purposes, the class is interpolated and thus hardcoded into the route.  So, if your Paperclip attachment definition looks like:
+
+```ruby
+class User
+  has_dynamic_attached_file :avatar, url: '/system/:class/:attachment/:id/:style'
+end
+```
+
+Dynamic Paperclip will generate the following route:
+
+```ruby
+get '/system/users/:attachment/:id/:style', to: 'DynamicPaperclip::AttachmentStyles#generate_user'
+```
+
+Now, in your view, you might call something like this:
+
+```ruby
+@photo.avatar.dynamic_url('50x50')
+```
+
+Which will return the following url (assuming a JPG avatar and a User ID of 42):
+
+```
+/system/users/avatars/42/dynamic_50x50.jpg?s=secrethash
+```
+
+When your visitor's browser requests that URL, if that particular style has already been processed,
+it'll be served up by your HTTP server, but if it hasn't, Rails will route it to our controller,
+which validates that "secrethash" to ensure that the dynamic URL was generated by your application,
+and not some third-party, then simply tells Paperclip to process that style by extracting the definition
+from the stye name, and then sends it back to your visitor via ``#send_file``.
+
+On subsequent requests, the attachment will already exist, and your HTTP server will simply return it without
+ever hitting your Rails application.  Sweet!
+
+Contributing
+------------
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,40 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'DynamicPaperclip'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/controllers/dynamic_paperclip/attachment_styles_controller.rb

@@ -0,0 +1,40 @@
+module DynamicPaperclip
+  class AttachmentStylesController < ApplicationController
+    def action_missing(name, *args, &block)
+      if name =~ /^generate_(.+)$/
+        send :generate, $1
+      end
+    end
+
+    private
+
+      def generate(class_name)
+        klass = class_name.camelize.constantize
+        attachment_name = params[:attachment].singularize.to_sym
+
+        # Ensure that we have a valid attachment name and an ID
+        raise Errors::UndefinedAttachment unless klass.attachment_definitions[attachment_name]
+        raise Errors::MissingID unless params[:id] || params[:id_partition]
+
+        id = params[:id] || id_from_partition(params[:id_partition])
+
+        attachment = klass.find(id).send(attachment_name)
+
+        # Only validate style name if it's dynamic,
+        # and only process style if it's dynamic and doesn't exist,
+        # otherwise we may just be fielding a request for
+        # an existing style (i.e. serve_static_assets is true)
+        if params[:style] =~ /^dynamic_/
+          raise Errors::InvalidHash unless DynamicPaperclip::UrlSecurity.valid_hash?(params[:s], params[:style])
+
+          attachment.process_dynamic_style params[:style] unless attachment.exists?(params[:style])
+        end
+
+        send_file attachment.path(params[:style]), :disposition => 'inline', :type => attachment.content_type
+      end
+
+      def id_from_partition(partition)
+        partition.gsub('/', '').to_i
+      end
+  end
+end

data/lib/dynamic_paperclip/attachment.rb

@@ -0,0 +1,64 @@
+module DynamicPaperclip
+  class Attachment < Paperclip::Attachment
+    attr_reader :dynamic_styles
+
+    def initialize(name, instance, options = {})
+      super
+
+      @dynamic_styles = {}
+
+      # Add existing dynamic styles
+      if instance.persisted?
+        path_with_wildcard = path('dynamic_*')
+        style_position = path_with_wildcard.index('dynamic_*')
+
+        Dir.glob(path_with_wildcard) do |file|
+          add_dynamic_style! file[style_position..-1].split('/').first
+        end
+      end
+    end
+
+    def styles
+      super.merge dynamic_styles
+    end
+
+    def process_dynamic_style(name)
+      add_dynamic_style! name
+      reprocess! name
+    end
+
+    def dynamic_url(definition)
+      raise DynamicPaperclip::Errors::SecretNotSet, "No secret has been configured. Please run the dynamic_paperclip:install generator." unless DynamicPaperclip.config.secret.present?
+
+      style_name = dynamic_style_name_from_definition(definition)
+
+      url = url(style_name)
+
+      delimiter_char = url.match(/\?.+=/) ? '&' : '?'
+
+      "#{url}#{delimiter_char}s=#{UrlSecurity.generate_hash(style_name)}"
+    end
+
+    private
+
+      # Generate style name from style definition,
+      # only supports strings at the moment
+      def dynamic_style_name_from_definition(options)
+        if options.is_a?(String)
+          "dynamic_#{URI.escape(options)}".to_sym
+        else
+          raise 'Only String options are supported with dynamic attachments'
+        end
+      end
+
+      # Reverse of #dynamic_style_name_from_definition,
+      # given a dynamic style name, extracts the definition (style options)
+      def style_definition_from_dynamic_style_name(name)
+        URI.unescape name[8..-1]
+      end
+
+      def add_dynamic_style!(name)
+        @dynamic_styles[name.to_sym] = Paperclip::Style.new(name, style_definition_from_dynamic_style_name(name), self)
+      end
+  end
+end

data/lib/dynamic_paperclip/config.rb

@@ -0,0 +1,5 @@
+module DynamicPaperclip
+  class Config
+    attr_accessor :secret
+  end
+end

data/lib/dynamic_paperclip/engine.rb

@@ -0,0 +1,4 @@
+module DynamicPaperclip
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/dynamic_paperclip/errors.rb

@@ -0,0 +1,18 @@
+module DynamicPaperclip
+  class Error < StandardError
+  end
+
+  module Errors
+    class UndefinedAttachment < DynamicPaperclip::Error
+    end
+
+    class MissingID < DynamicPaperclip::Error
+    end
+
+    class SecretNotSet < DynamicPaperclip::Error
+    end
+
+    class InvalidHash < DynamicPaperclip::Error
+    end
+  end
+end

data/lib/dynamic_paperclip/has_attached_file.rb

@@ -0,0 +1,47 @@
+module DynamicPaperclip
+  class HasAttachedFile < Paperclip::HasAttachedFile
+    def initialize(klass, name, options)
+      super
+
+      add_route!
+    end
+
+    private
+
+      # TODO: Are there any alternatives to literally copying this
+      #       method from Paperclip::HasAttachedFile to get Ruby to find
+      #       DynamicPaperclip::Attachment instead of Paperclip::Attachment?
+      def define_instance_getter
+        name = @name
+        options = @options
+
+        @klass.send :define_method, @name do |*args|
+          ivar = "@attachment_#{name}"
+          attachment = instance_variable_get(ivar)
+
+          if attachment.nil?
+            attachment = Attachment.new(name, self, options)
+            instance_variable_set(ivar, attachment)
+          end
+
+          if args.length > 0
+            attachment.to_s(args.first)
+          else
+            attachment
+          end
+        end
+      end
+
+      def add_route!
+        url = (@options[:url] || Attachment.default_options[:url]).gsub(':id_partition', '*id_partition').gsub(':class', @klass.name.underscore.pluralize)
+        action = "generate_#{@klass.name.underscore}"
+        default_attachment = @name.to_s.downcase.pluralize
+
+        Rails.application.routes do
+          get url,
+            :to => "DynamicPaperclip::AttachmentStyles##{action}",
+            :defaults => { :attachment => default_attachment }
+        end
+      end
+  end
+end

data/lib/dynamic_paperclip/paperclip_shim.rb

@@ -0,0 +1,7 @@
+module Paperclip
+  module ClassMethods
+    def has_dynamic_attached_file(name, options = {})
+      DynamicPaperclip::HasAttachedFile.define_on(self, name, options)
+    end
+  end
+end

data/lib/dynamic_paperclip/url_security.rb

@@ -0,0 +1,11 @@
+module DynamicPaperclip
+  module UrlSecurity
+    def self.generate_hash(style_name)
+      Digest::SHA1.hexdigest "#{DynamicPaperclip.config.secret}#{style_name}"
+    end
+
+    def self.valid_hash?(hash, style_name)
+      generate_hash(style_name) == hash
+    end
+  end
+end

data/lib/dynamic_paperclip/version.rb

@@ -0,0 +1,3 @@
+module DynamicPaperclip
+  VERSION = "0.0.1"
+end

data/lib/dynamic_paperclip.rb

@@ -0,0 +1,16 @@
+require 'paperclip'
+require "dynamic_paperclip/errors"
+require "dynamic_paperclip/config"
+require "dynamic_paperclip/engine"
+require "dynamic_paperclip/attachment"
+require "dynamic_paperclip/has_attached_file"
+require "dynamic_paperclip/paperclip_shim"
+require "dynamic_paperclip/url_security"
+
+module DynamicPaperclip
+  extend self
+
+  def config
+    @@config ||= Config.new
+  end
+end