fog-dragonfly 0.8.1

data/extra_docs/Rack.md

@@ -0,0 +1,52 @@
+Rack
+====
+For more info about using Rack applications, see the docs at {http://rack.rubyforge.org/}
+
+Basic usage involves storing data (e.g. images),
+then serving it in some form.
+
+A basic rackup file `config.ru`:
+
+    require 'rubygems'
+    require 'dragonfly'
+
+    Dragonfly[:my_app_name].configure do |c|
+      # ... configuration here
+    end
+
+    run Dragonfly:App[:my_app_name]
+
+See {file:Configuration} for more details.
+
+The basic flow is instantiate an app -> configure it -> run it.
+
+Example: Using to serve resized images
+--------------------------------------
+
+`config.ru`:
+
+    require 'rubygems'
+    require 'dragonfly'
+
+    app = Dragonfly[:images].configure_with(:imagemagick)
+
+    run app
+
+This enables the app to use all the ImageMagick goodies provided by Dragonfly (see {file:Configuration}).
+By default the {Dragonfly::DataStorage::FileDataStore file data store} is used.
+
+In the console:
+
+    app = Dragonfly[:images]
+
+    # Store
+    uid = app.store(File.new('path/to/image.png'))      # ===> unique uid
+
+    # Get the url for a thumbnail
+    url = app.fetch(uid).thumb('400x300').url           # ===> "/media/BAhbBlsHOgZmIg9hc..."
+
+Now when we visit the url `/media/BAhbBlsHOgZmIg9hc...` in the browser, we get a resized image!
+
+Mounting in Rack
+----------------
+See {file:URLs}

data/extra_docs/Rails2.md

@@ -0,0 +1,55 @@
+Using With Rails 2.3
+====================
+
+Setting up the quick way
+------------------------
+config/initializers/dragonfly.rb:
+
+    require 'dragonfly/rails/images'
+
+Setting up the more explicit way
+--------------------------------
+You can do the above explicitly.
+
+config/initializers/dragonfly.rb:
+
+    require 'dragonfly'
+
+    app = Dragonfly[:images]
+    app.configure_with(:imagemagick)
+    app.configure_with(:rails)
+
+    app.define_macro(ActiveRecord::Base, :image_accessor)
+
+environment.rb:
+
+    config.middleware.insert_after 'Rack::Lock', 'Dragonfly::Middleware', :images, '/media'
+    config.middleware.insert_before 'Dragonfly::Middleware', 'Rack::Cache', {
+      :verbose     => true,
+      :metastore   => "file:#{Rails.root}/tmp/dragonfly/cache/meta",
+      :entitystore => "file:#{Rails.root}/tmp/dragonfly/cache/body"
+    }
+
+Gems
+----
+environment.rb
+
+    config.gem 'dragonfly', '~>0.8.1'
+    config.gem 'rack-cache', :lib => 'rack/cache'
+
+Capistrano
+----------
+If using Capistrano with the above, you probably will want to keep the cache between deploys, so in deploy.rb:
+
+    namespace :dragonfly do
+      desc "Symlink the Rack::Cache files"
+      task :symlink, :roles => [:app] do
+        run "mkdir -p #{shared_path}/tmp/dragonfly && ln -nfs #{shared_path}/tmp/dragonfly #{release_path}/tmp/dragonfly"
+      end
+    end
+    after 'deploy:update_code', 'dragonfly:symlink'
+
+Use it!
+-------
+
+To see what you can do with the model accessors, see {file:Models}.

data/extra_docs/Rails3.md

@@ -0,0 +1,62 @@
+Using With Rails 3
+==================
+
+Setting up the quick way
+------------------------
+config/initializers/dragonfly.rb:
+
+    require 'dragonfly/rails/images'
+
+Setting up the more explicit way
+--------------------------------
+You can do the above explicitly.
+
+config/initializers/dragonfly.rb:
+
+    require 'dragonfly'
+
+    app = Dragonfly[:images]
+    app.configure_with(:imagemagick)
+    app.configure_with(:rails)
+
+    app.define_macro(ActiveRecord::Base, :image_accessor)
+
+application.rb:
+
+    config.middleware.insert_after 'Rack::Lock', 'Dragonfly::Middleware', :images, '/media'
+    config.middleware.insert_before 'Dragonfly::Middleware', 'Rack::Cache', {
+      :verbose     => true,
+      :metastore   => "file:#{Rails.root}/tmp/dragonfly/cache/meta",
+      :entitystore => "file:#{Rails.root}/tmp/dragonfly/cache/body"
+    }
+
+Gemfile
+-------
+
+    gem 'dragonfly', '~>0.8.1'
+    gem 'rack-cache', :require => 'rack/cache'
+
+Capistrano
+----------
+If using Capistrano with the above, you probably will want to keep the cache between deploys, so in deploy.rb:
+
+    namespace :dragonfly do
+      desc "Symlink the Rack::Cache files"
+      task :symlink, :roles => [:app] do
+        run "mkdir -p #{shared_path}/tmp/dragonfly && ln -nfs #{shared_path}/tmp/dragonfly #{release_path}/tmp/dragonfly"
+      end
+    end
+    after 'deploy:update_code', 'dragonfly:symlink'
+
+Use it!
+-------
+
+To see what you can do with the model accessors, see {file:Models}.
+
+Mounting in routes.rb
+---------------------
+Instead of mounting as a middleware, you could skip that bit and mount directly in the routes.rb file:
+
+    match '/media(/:dragonfly)', :to => Dragonfly[:images]
+
+Make sure the the path prefix matches the Dragonfly app's configured url_path_prefix (which is /media by default for Rails).

data/extra_docs/Sinatra.md

@@ -0,0 +1,25 @@
+Sinatra
+=======
+You can use {Dragonfly::Job Job}'s `to_response` method like so:
+
+    app = Dragonfly[:images].configure_with(:imagemagick)
+
+    get '/images/:size.:format' do |size, format|
+      app.fetch_file('~/some/image.png').thumb(size).encode(format).to_response(env)
+    end
+
+`to_response` returns a rack-style response array with status, headers and body.
+
+NOTE: uids from the datastore currently have slashes and dots in them so may cause problems when using ':uid' as
+a path segment.
+
+or you can mount as a middleware, like in rails:
+
+    Dragonfly[:images].configure_with(:imagemagick) do |c|
+      c.url_path_prefix = '/media'
+    end
+
+    use Dragonfly::Middleware, :images, '/media'
+
+    get '/' #... do
+      # ...

data/extra_docs/URLs.md

@@ -0,0 +1,169 @@
+URLs
+====
+
+We can get urls for any kind of job:
+
+    app = Dragonfly[:images]
+
+    app.fetch('my_uid').process(:flip).url                    # "/BAhbBlsH..."
+    app.generate(:text, 'hello').thumb('500x302').gif.url     # "/BAhbCFsHOgZ..."
+
+Path prefix
+-----------
+If the app is mounted with a path prefix (such as when using in Rails), then we need to add this prefix
+to the urls:
+
+    app.url_path_prefix = '/media'
+
+(or done in a configuration block).
+
+    app.fetch('my_uid').url                                  # "/media/BAhbBlsH..."
+
+This is done for you when using {file:Configuration Rails defaults}.
+
+You can override it using
+
+    app.fetch('my_uid').url(:path_prefix => '/images')       # "/images/BAhbBlsH..."
+
+Host
+----
+You can also set a host for the urls
+
+    app.url_host = 'http://some.host'
+    app.fetch('my_uid').url                                  # "http://some.host/BAhb..."
+
+    app.fetch('my_uid').url(:host => 'http://localhost:80')  # "http://localhost:80/BAh..."
+
+Suffix
+------
+You can set a suffix for the urls (for example if some other component behaves badly with urls that have no file extension).
+
+Note that this has no effect on the response.
+
+    app.url_suffix = '.jpg'
+    app.fetch('some/uid').url                                # "...b21lL3VpZA.jpg"
+
+You can also pass it a block, that yields the {Dragonfly::Job Job}, for example:
+
+    app.url_suffix = proc{|job|
+      "/#{job.uid_basename}#{job.encoded_extname || job.uid_extname}"
+    }
+
+    app.fetch('2007/painting.pdf').url                       # "...eS5ib2R5/painting.pdf"
+    app.fetch('2007/painting.pdf').encode(:png).url          # "...gZlOgbmc/painting.png"
+
+And you can override it:
+
+    app.fetch('some/uid').url(:suffix => '/yellowbelly')     # "...b21lL3VpZA/yellowbelly"
+
+Content-Disposition
+-------------------
+You can manually set the content-disposition of the response:
+
+    app.content_disposition = :attachment    # should be :inline or :attachment (or :hidden)
+
+`:attachment` tells the browser to download it, `:inline` tells it to display in-browser if possible.
+
+You can also use a block:
+
+    app.content_disposition = proc{|job, request|
+      if job.format == :jpg || request['d'] == 'inline' # request is a Rack::Request object
+        :inline
+      else
+        :attachment
+      end
+    }
+
+Downloaded filename
+-------------------
+To specify the filename the browser uses for 'Save As' dialogues:
+
+    app.content_filename = proc{|job, request|
+      "#{job.basename}_#{job.process_steps.first.name}.#{job.encoded_format || job.ext}"
+    }
+
+This will for example give the following filenames for the following jobs:
+
+    app.fetch('some/tree.png').process(:greyscale)      # -> 'tree_greyscale.png'
+    app.fetch('some/tree.png').process(:greyscale).gif  # -> 'tree_greyscale.gif'
+
+By default the original filename is used, with a modified extension if it's been encoded.
+
+Routed Endpoints
+----------------
+You can also use a number of Rack-based routers and create Dragonfly endpoints.
+
+If we have an app set up for using ImageMagick:
+
+    app = Dragonfly[:images].configure_with(:imagemagick)
+
+Then to get the url '/text/hello' to display the text "hello"...
+
+Rails 3 (routes.rb):
+
+    match '/text/:text' => app.endpoint{|params, app|
+      app.generate(:text, params[:text])
+    }
+
+{http://github.com/josh/rack-mount Rack-Mount}:
+
+    Routes = Rack::Mount::RouteSet.new do |set|
+
+      set.add_route app.endpoint{|params, a| a.generate(:text, params[:text]) },
+                      :path_info => %r{/text/(?:<text>.+)}
+
+      # ...
+
+    end
+
+{http://github.com/joshbuddy/usher Usher}:
+
+    routes = Usher::Interface.for(:rack) do
+      add('/text/:text').to app.endpoint{|params, app|
+        app.generate(:text, params[:text])
+      }
+    end
+
+{http://github.com/joshbuddy/http_router HTTP Router}:
+
+    r = HttpRouter.new
+    r.add('/text/:text').to app.endpoint{|params, app|
+      app.generate(:text, params[:text])
+    }
+
+In each case the url will need to be generated by the router of choice, or manually.
+
+Simple Endpoints
+----------------
+{Dragonfly::Job Job} objects can also be turned straight into Rack endpoints using `to_app`, e.g. in Rails 3:
+
+    match '/beach' => app.fetch_file('~/some/image.png').thumb('100x100#').jpg.to_app
+
+
+Denial-of-service attacks
+-------------------------
+Although the standard urls are fairly cryptic, a malicious person who knows the Dragonfly source code could potentially
+work out how to generate urls to spam your server with heavy requests, e.g. resize to 100000 by 100000 pixels.
+
+Therefore the app can be protected by requiring the presence of a "DOS-protection" SHA in the urls:
+
+    app.configure do |c|
+      c.protect_from_dos_attacks = true
+      c.secret = 'You should supply some random secret here'
+    end
+
+Then the standard generated urls will have a SHA query parameter attached:
+
+    app.fetch('my_uid').url          # "/BAhbBlsHOgZmIghzZGY?s=df76ba27"
+
+Any requests without the correct SHA parameter result in a 400 (bad parameters) error response.
+
+You can also validate for a correct SHA using routed endpoints:
+
+    match '/text/:text' => app.endpoint{|params, app|
+      app.generate(:text, params[:text]).validate_sha!(params[:sha])
+    }
+
+... where obviously you need to pass in a 'sha' parameter to the url, which can be found using
+
+    app.generate(:text, 'some text').sha

data/features/3.0.3.feature

@@ -0,0 +1,8 @@
+Feature: champion uses dragonfly in his Rails 3.0.3 application
+  In order to be a champion
+  A user uses dragonfly in his Rails 3.0.3 application
+
+  Scenario: Set up dragonfly using initializer
+    Given a Rails 3.0.3 application set up for using dragonfly
+    Then the manage_album_images cucumber features in my Rails 3.0.3 app should pass
+    And the text_images cucumber features in my Rails 3.0.3 app should pass

data/features/images.feature

@@ -0,0 +1,47 @@
+Feature: champion uses dragonfly to process images
+  In order to be a champion
+  A user uses dragonfly
+
+  Background:
+    Given we are using the app for images
+    Given a stored image "beach.png" with dimensions 200x100
+
+  Scenario: Go to url for original
+    When I go to the url for "beach.png", with format 'png'
+    Then the response should be OK
+    And the response should have mime-type 'image/png'
+    And the image should have width '200'
+    And the image should have height '100'
+    And the image should have format 'png'
+
+  Scenario: Go to url for changed format version
+    When I go to the url for "beach.png", with format 'gif'
+    Then the response should be OK
+    And the response should have mime-type 'image/gif'
+    And the image should have width '200'
+    And the image should have height '100'
+    And the image should have format 'gif'
+
+  Scenario: Go to url for soft resized version
+    When I go to the url for "beach.png", with format 'png' and resize geometry '100x150'
+    Then the response should be OK
+    And the response should have mime-type 'image/png'
+    And the image should have width '100'
+    And the image should have height '50'
+    And the image should have format 'png'
+
+  Scenario: Go to url for hard resized version
+    When I go to the url for "beach.png", with format 'png' and resize geometry '100x150!'
+    Then the response should be OK
+    And the response should have mime-type 'image/png'
+    And the image should have width '100'
+    And the image should have height '150'
+    And the image should have format 'png'
+
+  Scenario: use a parameters shortcut
+    When I go to the url for "beach.png", with shortcut '100x150!'
+    Then the response should be OK
+    And the response should have mime-type 'image/png'
+    And the image should have width '100'
+    And the image should have height '150'
+    And the image should have format 'png'

data/features/no_processing.feature

@@ -0,0 +1,14 @@
+Feature: winner uses dragonfly to serve different kinds of files
+  In order to be a winner
+  As a potential loser
+  I want to be a winner
+
+  Background:
+    Given we are using the app for files
+
+  Scenario: Go to url for original, without extension
+    Given a stored file "sample.docx"
+    When I go to the url for "sample.docx"
+    Then the response should be OK
+    And the response should have mime-type 'application/zip'
+    And the response should have the same content as the file "sample.docx"

data/features/rails_2.3.5.feature

@@ -0,0 +1,7 @@
+Feature: champion uses dragonfly in his Rails 2.3.5 application
+  In order to be a champion
+  A user uses dragonfly in his Rails 2.3.5 application
+
+  Scenario: Set up dragonfly using the provided initializer
+    Given a Rails 2.3.5 application set up for using dragonfly
+    Then the manage_album_images cucumber features in my Rails 2.3.5 app should pass