attached 0.0.1

data/Gemfile

@@ -0,0 +1,5 @@
+source 'http://rubygems.org'
+
+gem 'rails'
+
+gem 'aws-s3', :require => 'aws/s3'

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Kevin Sylvestre
+
+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.rdoc

@@ -0,0 +1,53 @@
+= Attached
+
+Attached is a Ruby on Rails file attachment tool that lets users upload to the cloud, then process in the cloud. The tool supports Amazon S3 by default. It surpasses Paperclip by providing built-in support for direct uploads to the cloud and by allowing integration with cloud based processing tools. However, in almost every other way Paperclip is better. The source code inspired (and copied) from Paperclip. If you aren't working in the cloud exclusively then this isn't for you!
+
+== Installation
+
+  gem install attached
+  
+== Examples
+
+Migration:
+
+  class CreateVideo < ActiveRecord::Migration
+    def self.up
+      create_table :videos do |t|
+        t.string :video_extension
+        t.integer :video_size
+
+        t.timestamps
+      end
+    end
+
+    def self.down
+      drop_table :videos
+    end
+  end
+
+Model:
+  
+  has_attached :video, :styles => { 
+    :mp4_720p => { :extension => 'mp4' },
+    :mp4_480p => { :extension => 'mp4' },
+    :ogv_720p => { :extension => 'ogv' },
+    :ogv_480p => { :extension => 'ogv' },
+  }
+  
+Form:
+
+  <%= form_for @video, :html => { :multipart => true } do |form| %>
+    <%= form.file_field :video %>
+    <p class="errors"><%= @video.errors[:video] %></p>
+  <% end %>
+  
+View:
+
+  <video>
+    <source src="<%= @video.video.url(:mp4_480p) %>" />
+    <source src="<%= @video.video.url(:ogv_480p) %>" />
+  </video>
+  
+== Copyright
+
+Copyright (c) 2010 Kevin Sylvestre. See LICENSE for details.

data/lib/attached.rb

@@ -0,0 +1,189 @@
+require 'attached/attachment'
+require 'attached/railtie'
+
+
+module Attached  
+  
+  
+  def self.included(base)
+    base.extend ClassMethods
+  end
+  
+  
+  module ClassMethods
+    
+    
+    # Initialize attached options used for communicating between class and instance methods.
+    
+    def initialize_attached_options
+      write_inheritable_attribute(:attached_options, {})
+    end
+    
+    
+    # Access attached options used for communicating between class and instance methods.
+    
+    def attached_options
+      read_inheritable_attribute(:attached_options)
+    end
+    
+    
+    # Add an attachment to a class.
+    #
+    # Options:
+    #
+    # * :styles  - 
+    # * :storage - 
+    #
+    # Usage:
+    #
+    #   has_attached :avatar
+    #   has_attached :avatar, :storage => :s3
+    #   has_attached :clip, styles => [ :mp4, :ogv ]
+    #   has_attached :clip, styles => { :main => { :size => "480p", :format => "mp4" } }
+    
+    def has_attached(name, options = {})
+      
+      include InstanceMethods
+      
+      initialize_attached_options unless attached_options
+      attached_options[name] = options
+      
+      after_save :save_attached
+      after_destroy :destroy_attached
+      
+      define_method name do
+        attachment_for(name)
+      end
+      
+      define_method "#{name}=" do |file|
+        attachment_for(name).assign(file)
+      end
+
+      define_method "#{name}?" do
+        attachment_for(name).file?
+      end
+      
+      after_validation do
+        
+        self.errors[:"#{name}_size"].each do |message|
+          self.errors.add(name, message)
+        end
+        
+        self.errors[:"#{name}_extension"].each do |message|
+          self.errors.add(name, message)
+        end
+        
+        self.errors.delete(:"#{name}_size")
+        self.errors.delete(:"#{name}_extension")
+        
+      end
+      
+    end
+    
+    
+    # Validates an attached size in a specified range or minimum and maximum. 
+    #
+    # Options:
+    #
+    # * :message - string to be displayed with :minimum and :maximum variables
+    # * :minimum - integer for the minimum byte size of the attached
+    # * :maximum - integer for the maximum byte size of teh attached
+    # * :in - range of bytes for file
+    #
+    # Usage:
+    #   
+    #   validates_attached_size :avatar, :range => 10.megabytes .. 20.megabytes
+    #   validates_attached_size :avatar, :minimum => 10.megabytes, :maximum => 20.megabytes
+    #   validates_attached_size :avatar, :message => "size must be between :minimum and :maximum bytes"
+    
+    def validates_attached_size(name, options = {})
+      
+      message = options[:message] || "size must be between :minimum and :maximum bytes"
+       
+      minimum = options[:minimum] || options[:in] && options[:in].first || (0.0 / 1.0)
+      maximum = options[:maximum] || options[:in] && options[:in].last  || (1.0 / 0.0)
+       
+      range = minimum..maximum
+      
+      message.gsub!(/:minimum/, minimum.to_s)
+      message.gsub!(/:maximum/, maximum.to_s)
+      
+      validates_inclusion_of :"#{name}_size", :in => range, :message => message, 
+        :if => options[:if], :unless => options[:unless]
+      
+    end
+    
+    
+    # Validates that an attachment is included.
+    #
+    # Options:
+    #
+    # * :message - string to be displayed
+    #
+    # Usage:
+    #
+    #   validates_attached_presence :avatar
+    #   validates_attached_presence :avatar, :message => "must be attached"
+    
+    def validates_attached_presence(name, options = {})
+      
+      message = options[:message] || "must be attached"
+      
+      validates_presence_of :"#{name}_extension", :message => message,
+        :if => options[:if], :unless => options[:unless]
+      
+    end
+    
+    
+  end
+  
+  
+  module InstanceMethods
+    
+    
+    # Create or access attachment.
+    #
+    # Usage:
+    # 
+    #    attachment_for :avatar
+    
+    def attachment_for(name)
+      @_attached_attachments ||= {}
+      @_attached_attachments[name] ||= Attachment.new(name, self, self.class.attached_options[name])
+    end
+    
+    
+    # Log and save all attached (using specified storage).
+    #
+    # Usage:
+    #
+    #   before_save :save_attached
+    
+    def save_attached
+      logger.info "[attached] save attached"
+      
+      self.class.attached_options.each do |name, options| 
+        attachment_for(name).save
+      end
+    end
+    
+    
+    # Log and destroy all attached (using specified storage).
+    #
+    # Usage:
+    #
+    #   before_save :destroy_attached
+    
+    def destroy_attached
+      logger.info "[attached] destroy attached"
+      
+      self.class.attached_options.each do |name, options|
+        attachment_for(name).destroy
+      end
+    end
+    
+    
+  end
+  
+  
+end

data/lib/attached/attachment.rb

@@ -0,0 +1,167 @@
+require 'attached/storage'
+
+module Attached
+  
+  class Attachment
+    
+    
+    attr_reader :file
+    attr_reader :name
+    attr_reader :instance
+    attr_reader :options
+    attr_reader :storage
+    
+    
+    def self.options
+      @options ||= {
+        :storage  => :fs,
+        :protocol => 'http',
+        :path     => "/:name/:style/:id:extension",
+        :styles   => {},
+      }
+    end
+    
+    
+    # Initialize a new attachment by providing a name and the instance the attachment is associated with.
+    #
+    # Parameters:
+    # 
+    # * name        - The name for the attachment such as 'avatar' or 'photo'
+    # * instance    - The instance the attachment is attached to
+    #
+    # Options:
+    #
+    # * :path        - The location where the attachment is stored
+    # * :storage     - The storage medium represented as a symbol such as ':s3' or ':fs'
+    # * :credentials - A file, hash, or path used to authenticate with the specified storage medium
+    
+    def initialize(name, instance, options = {})
+      @name       = name
+      @instance   = instance
+      
+      @options    = self.class.options.merge(options)
+    end
+    
+    
+    # Usage:
+    #
+    #   @object.avatar.assign(...)
+    
+    def assign(file)
+      @file = file
+      
+      extension = File.extname(file.original_filename)
+      
+      instance_set :size, file.size
+      instance_set :extension, extension
+    end
+    
+    
+    # Usage:
+    #
+    #   @object.avatar.save
+    
+    def save
+      @storage ||= Attached::Storage.medium(options[:storage], options[:credentials])
+      
+      storage.save(self.file, self.path) if self.file
+    end
+    
+    
+    # Usage:
+    #
+    #   @object.avatar.destroy
+    
+    def destroy
+      @storage ||= Attached::Storage.medium(options[:storage], options[:credentials])
+      
+      storage.destroy(self.path)
+    end
+    
+    
+    # Usage:
+    #
+    #   @object.avatar.url
+    #   @object.avatar.url(:small)
+    #   @object.avatar.url(:large)
+    
+    def url(style = :original)
+      @storage ||= Attached::Storage.medium(options[:storage], options[:credentials])
+      
+      return "#{options[:protocol]}://#{@storage.host}#{path(style)}"
+    end
+    
+    
+    # Access the URL 
+    #
+    # Usage:
+    #
+    #   @object.avatar.url
+    #   @object.avatar.url(:small)
+    #   @object.avatar.url(:large)
+    
+    def path(style = :original)
+      path = String.new(options[:path])
+      
+      path.gsub!(/:id/, instance.id.to_s)
+      path.gsub!(/:name/, name.to_s)
+      path.gsub!(/:style/, style.to_s)
+      path.gsub!(/:extension/, extension(style).to_s)
+
+      return path
+    end
+    
+    # Access the size for an attachment.
+    #
+    # Usage:
+    #
+    # @object.avatar.size
+    
+    def size
+      return instance_get(:size)
+    end
+    
+    
+    # Access the extension for an attachment.
+    #
+    # Usage:
+    #
+    # @object.avatar.extension
+    
+    def extension(style)
+      return options[:styles][style][:extension] if style and options[:styles][style]
+      
+      return instance_get(:extension)
+    end
+    
+    
+  private
+  
+  
+    # Helper function for setting instance variables.
+    # 
+    # Usage:
+    #
+    #   self.instance_set(size, 12345)
+  
+    def instance_set(attribute, value)
+      setter = :"#{self.name}_#{attribute}="
+      self.instance.send(setter, value)
+    end
+    
+    
+    # Helper function for getting instance variables.
+    #
+    # Usage:
+    #
+    # self.instance_get(size)
+    
+    def instance_get(attribute)
+      getter = :"#{self.name}_#{attribute}"
+      self.instance.send(getter)
+    end
+
+    
+  end
+  
+end

data/lib/attached/railtie.rb

@@ -0,0 +1,12 @@
+require 'attached'
+require 'rails'
+
+module Attached
+  class Railtie < Rails::Railtie
+    initializer 'attached.initialize' do
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::Base.send :include, Attached
+      end
+    end
+  end
+end

data/lib/attached/storage.rb

@@ -0,0 +1,25 @@
+require 'attached/storage/base'
+require 'attached/storage/fs'
+require 'attached/storage/s3'
+
+module Attached
+  module Storage
+    
+    # Create a storage object given a medium and credentials.
+    #
+    # Usage:
+    #
+    #   Attached::Storage.medium(:fs)
+    #   Attached::Storage.medium(:s3)
+    
+    def self.medium(storage = :fs, credentials = nil)
+      
+      case storage
+      when :fs then return Attached::Storage::FS.new(credentials)
+      when :s3 then return Attached::Storage::S3.new(credentials)
+      end
+      
+    end
+    
+  end
+end

data/lib/attached/storage/base.rb

@@ -0,0 +1,72 @@
+require 'attached/storage/base'
+
+module Attached
+  module Storage
+    class Base
+      
+      
+      # Helper for parsing credentials from a hash, file, or string.
+      #
+      # Usage:
+      #
+      #   parse({...}) 
+      #   parse(File.open(...))
+      #   Parse("...")
+      
+      def parse(credentials)
+        case credentials
+        when Hash    then credentials
+        when File    then YAML::load(credentials)[Rails.env]
+        when String  then YAML::load(File.read(credentials))[Rails.env]
+        else raise ArgumentError.new("credentials must be a hash, file, or string")
+        end
+      end
+      
+      
+      # Create a new file system storage interface supporting save and destroy operations.
+      #
+      # Usage:
+      #
+      #   Base.new()
+      
+      def initialize(credentials = nil)
+        raise NotImplementedError.new
+      end
+      
+      
+      # Access the host (e.g. localhost:3000) for a storage service.
+      #
+      # Usage:
+      #
+      #   storage.host
+      
+      def host()
+        raise NotImplementedError.new
+      end
+      
+      
+      # Save a file to a given path (abstract).
+      #
+      # Parameters:
+      #
+      # * file - The file to save.
+      # * path - The path to save.
+      
+      def save(file, path)
+        raise NotImplementedError.new
+      end
+      
+      
+      # Destroy a file at a given path (abstract).
+      #
+      # Parameters:
+      #
+      # * path - The path to destroy.
+      
+      def destroy(path)
+        raise NotImplementedError.new
+      end
+      
+    end
+  end
+end

data/lib/attached/storage/fs.rb

@@ -0,0 +1,39 @@
+module Attached
+  module Storage
+    class FS < Base
+      
+      
+      # Create a new file system storage interface supporting save and destroy operations.
+      #
+      # Usage:
+      #
+      #   FS.new()
+      
+      def initialize(credentials = nil)
+        credentials = parse(credentials)
+      end
+      
+      
+      # Save a file to a given path on a file system.
+      #
+      # Parameters:
+      #
+      # * file - The file to save.
+      # * path - The path to save.
+      
+      def save(file, path)
+      end
+      
+      
+      # Destroy a file at a given path on a file system.
+      #
+      # Parameters:
+      #
+      # * path - The path to destroy.
+      
+      def destroy(path)
+      end
+      
+    end
+  end
+end

data/lib/attached/storage/s3.rb

@@ -0,0 +1,77 @@
+module Attached
+  module Storage
+    class S3 < Base
+      
+      attr_reader :bucket
+      attr_reader :access_key_id
+      attr_reader :secret_access_key
+      
+      
+      # Create a new Amazon S3 storage interface supporting save and destroy operations.
+      #
+      # Usage:
+      #
+      #   Attached::Storage::S3.new()
+      #   Attached::Storage::S3.new("#{Rails.root}/config/s3.yml")
+      
+      def initialize(credentials = "#{Rails.root}/config/s3.yml")
+        credentials = parse(credentials)
+        
+        @bucket            = credentials[:bucket] || credentials['bucket']
+        @access_key_id     = credentials[:access_key_id] || credentials['access_key_id']
+        @secret_access_key = credentials[:secret_access_key] || credentials['secret_access_key']
+      end
+      
+      
+      # Access the host (e.g. bucket.s3.amazonaws.com) for a storage service.
+      #
+      # Usage:
+      #
+      #   storage.host
+      
+      def host()
+        "#{self.bucket}.s3.amazonaws.com"
+      end
+      
+      
+      # Save a file to a given path on Amazon S3.
+      #
+      # Parameters:
+      #
+      # * file - The file to save.
+      # * path - The path to save.
+      
+      def save(file, path)
+        connect()
+        AWS::S3::S3Object.store(path, file, bucket)
+      end
+      
+      
+      # Destroy a file at a given path on Amazon S3.
+      #
+      # Parameters:
+      #
+      # * path - The path to destroy.
+      
+      def destroy(path)
+        connect()
+        AWS::S3::S3Object.delete(path, bucket)
+      end
+      
+      
+      private
+      
+      
+      # Connect to an Amazon S3 server.
+      
+      def connect
+        return AWS::S3::Base.establish_connection!(
+          :access_key_id => self.access_key_id, 
+          :secret_access_key => self.secret_access_key
+        )
+      end
+      
+      
+    end
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: attached
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Kevin Sylvestre
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-01 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: aws-s3
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: Attached is a Ruby on Rails cloud attachment and processor library inspired by Paperclip. Attached lets users push files to the cloud, then perform remote processing on the files.
+email: 
+- kevin@ksylvest.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/attached/attachment.rb
+- lib/attached/railtie.rb
+- lib/attached/storage/base.rb
+- lib/attached/storage/fs.rb
+- lib/attached/storage/s3.rb
+- lib/attached/storage.rb
+- lib/attached.rb
+- README.rdoc
+- LICENSE
+- Gemfile
+has_rdoc: true
+homepage: http://github.com/ksylvest/attached
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: An attachment library designed with cloud processors in mind
+test_files: []
+