dassets 0.3.0 → 0.4.0

data/README.md

@@ -17,33 +17,40 @@ Dassets.configure do |c|
   # tell Dassets what the root path of your app is
   c.root_path '/path/to/app/root'
 
-  # tell Dassets where to write the digests
-  c.digests_path '/path/to/.digests' # default: '{source_path}/.digests'
-
   # tell Dassets where to look for source files and (optionally) how to filter those files
   c.source_path 'lib/asset_files' # default: '{root_path}/app/assets'
   c.source_filter proc{ |paths| paths.select{ |p| ... } }
   # --OR--
-  c.sources 'lib/asset_files' do |paths|
+  c.source 'lib/asset_files' do |paths|
     # return the filtered source path list
     paths.select{ |p| ... }
   end
 
-  # tell Dassets where to write output files to
-  # it works best to *not* output to your public dir if using fingerprinting
-  c.output_path '/lib/assets_output' # default: '{source_path}/public'
+  # (optional) tell Dassets where to store digested asset files
+  # if none given, Dassets will not write any digested output
+  # use this to "cache" digested assets to the public dir (for example)
+  c.file_store 'public' # default: `NullFileStore.new`
 
 end
 ```
 
 ### Digest
 
+You can use the CLI to digest your source files on demand:
+
 ```
-$ dassets digest                      # rebuild the .digests for all asset files, OR
-$ dassets digest /path/to/asset/file  # update the digest for just one file
+$ dassets digest                       # digest all source files, OR
+$ dassets digest /path/to/source/file  # digest some specific files
 ```
 
-Use the CLI to build your digests file.  Protip: use guard to auto rebuild digests every time you edit an asset file.  TODO: link to some guard tools or docs.
+Or you can programmatically digest files as needed:
+
+```ruby
+Dassets.digest_source_files                           # digest all source files, OR
+Dassets.digest_source_files ['/path/to/source/file']  # digest just some specific files
+```
+
+Digesting involves combining, compiling, fingerprinting, and outputting each source file.  Once a source has been digested, it is available for linking, serving, and/or caching.
 
 ### Link To
 
@@ -70,6 +77,31 @@ In production, use the CLI to cache your digested asset files to the public dir:
 $ dassets cache /path/to/public/dir
 ```
 
+TODO: programmatically cache asset files
+
+## Compiling
+
+Dassets can handle compiling your asset source as part of its digest pipeline.  It does this via "engines".  Engines transform source extensions and content.
+
+Engines are "registered" with dassets based on source extensions.  Name your source file with registered extensions and those engines will be used to compile your source content.
+
+### Some Dassets Engines
+
+Examples are key here, so check out some of the Dasset's engines available:
+
+TODO
+
+### Creating your own Engine
+
+* create a class that subclasses `Dassets::Engine`
+* override the `ext` method to specify how the input source extension should be handled
+* override the `compile` method to specify how the input content should be transformed
+* register your engine class with Dassets
+
+## Combinations
+
+TODO
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/dassets.rb

@@ -4,61 +4,51 @@ require 'ns-options'
 
 require 'dassets/version'
 require 'dassets/root_path'
-require 'dassets/digests'
+require 'dassets/file_store'
+require 'dassets/default_cache'
 require 'dassets/engine'
+require 'dassets/asset_file'
 
 ENV['DASSETS_ASSETS_FILE'] ||= 'config/assets'
 
 module Dassets
 
-  def self.config;  @config  ||= Config.new;      end
-  def self.sources; @sources ||= Set.new;         end
-  def self.digests; @digests ||= NullDigests.new; end
-
+  def self.config;  @config  ||= Config.new; end
   def self.configure(&block)
     block.call(self.config)
   end
 
-  def self.reset
-    @sources = @digests = nil
-  end
-
   def self.init
     require self.config.assets_file
-    @sources = SourceList.new(self.config)
-    @digests = Digests.new(self.config.digests_path)
   end
 
-  def self.[](asset_path)
-    self.digests.asset_file(asset_path)
+  def self.[](digest_path)
+    AssetFile.new(digest_path)
   end
 
   # Cmds
 
   def self.digest_source_files(paths=nil)
-    require 'dassets/cmds/digest_cmd'
-    Cmds::DigestCmd.new(paths).run
+    require 'dassets/digest_cmd'
+    DigestCmd.new(paths).run
   end
 
   class Config
     include NsOptions::Proxy
 
-    option :root_path,    Pathname, :required => true
-    option :digests_path, Pathname, :required => true
-    option :output_path,  RootPath, :required => true
-
-    option :assets_file,  Pathname, :default => ENV['DASSETS_ASSETS_FILE']
-    option :source_path,  RootPath, :default => proc{ "app/assets" }
-    option :source_filter, Proc, :default => proc{ |paths| paths }
+    option :root_path,     Pathname,  :required => true
+    option :assets_file,   Pathname,  :default => ENV['DASSETS_ASSETS_FILE']
+    option :source_path,   RootPath,  :default => proc{ "app/assets" }
+    option :source_filter, Proc,      :default => proc{ |paths| paths }
+    option :file_store,    FileStore, :default => proc{ NullFileStore.new }
 
     attr_reader :engines
+    attr_accessor :cache
 
     def initialize
-      super({
-        :digests_path => proc{ File.join(self.source_path, '.digests') },
-        :output_path  => proc{ File.join(self.source_path, 'public')   }
-      })
+      super
       @engines = Hash.new{ |k,v| Dassets::NullEngine.new }
+      @cache = DefaultCache.new
     end
 
     def source(path=nil, &filter)
@@ -76,8 +66,6 @@ module Dassets
       paths = Set.new
       paths += Dir.glob(File.join(config.source_path, "**/*"))
       paths.reject!{ |path| !File.file?(path) }
-      paths.reject!{ |path| path =~ /^#{config.output_path}/ }
-      paths.reject!{ |path| path =~ /^#{config.digests_path}/ }
 
       config.source_filter.call(paths).sort
     end

data/lib/dassets/asset_file.rb

@@ -1,66 +1,69 @@
-require 'digest/md5'
 require 'rack/utils'
 require 'rack/mime'
+require 'dassets/source_cache'
 
 module Dassets; end
 class Dassets::AssetFile
 
-  def self.from_abs_path(abs_path)
-    rel_path = abs_path.sub("#{Dassets.config.output_path}/", '')
-    md5  = Digest::MD5.file(abs_path).hexdigest
-    self.new(rel_path, md5)
+  attr_reader :digest_path, :dirname, :extname, :basename, :source_cache
+
+  def initialize(digest_path)
+    @digest_path = digest_path
+    @dirname  = File.dirname(@digest_path)
+    @extname  = File.extname(@digest_path)
+    @basename = File.basename(@digest_path, @extname)
+    @source_cache = Dassets::SourceCache.new(@digest_path, Dassets.config.cache)
   end
 
-  attr_reader :path, :md5, :dirname, :extname, :basename
-  attr_reader :output_path, :url, :href
+  def digest!
+    return if !self.exists?
+    Dassets.config.file_store.save(self.url){ self.content }
+  end
 
-  def initialize(rel_path, md5)
-    @path, @md5 = rel_path, md5
-    @dirname  = File.dirname(@path)
-    @extname  = File.extname(@path)
-    @basename = File.basename(@path, @extname)
+  def url
+    @url ||= begin
+      url_basename = "#{@basename}-#{self.fingerprint}#{@extname}"
+      File.join(@dirname, url_basename).sub(/^\.\//, '').sub(/^\//, '')
+    end
+  end
 
-    @output_path = File.join(Dassets.config.output_path, @path)
+  def href
+    @href ||= "/#{self.url}"
+  end
 
-    url_basename = "#{@basename}-#{@md5}#{@extname}"
-    @url = File.join(@dirname, url_basename).sub(/^\.\//, '').sub(/^\//, '')
-    @href = "/#{@url}"
+  def fingerprint
+    return nil if !self.exists?
+    @fingerprint ||= @source_cache.fingerprint
   end
 
   def content
-    @content ||= if File.exists?(@output_path) && File.file?(@output_path)
-      File.read(@output_path)
-    end
+    return nil if !self.exists?
+    @content ||= @source_cache.content
   end
 
   def mtime
-    @mtime ||= if File.exists?(@output_path) && File.file?(@output_path)
-      File.mtime(@output_path).httpdate
-    end
+    return nil if !self.exists?
+    @mtime ||= @source_cache.mtime
   end
 
-  # We check via File::size? whether this file provides size info via stat,
-  # otherwise we have to figure it out by reading the whole file into memory.
   def size
-    @size ||= if File.exists?(@output_path) && File.file?(@output_path)
-      File.size?(@output_path) || Rack::Utils.bytesize(self.content)
-    end
+    return nil if !self.exists?
+    @size ||= Rack::Utils.bytesize(self.content)
   end
 
   def mime_type
-    @mime_type ||= if File.exists?(@output_path) && File.file?(@output_path)
-      Rack::Mime.mime_type(@extname)
-    end
+    return nil if !self.exists?
+    @mime_type ||= Rack::Mime.mime_type(@extname)
   end
 
   def exists?
-    File.exists?(@output_path) && File.file?(@output_path)
+    @source_cache.exists?
   end
 
   def ==(other_asset_file)
     other_asset_file.kind_of?(Dassets::AssetFile) &&
-    self.path == other_asset_file.path &&
-    self.md5 == other_asset_file.md5
+    self.digest_path == other_asset_file.digest_path &&
+    self.fingerprint == other_asset_file.fingerprint
   end
 
 end

data/lib/dassets/default_cache.rb

@@ -0,0 +1,29 @@
+require 'thread'
+
+# this is a thread-safe in-memory cache for use with the `SourceCache` that
+# only caches source fingerprint keys.  there are a few reasons for using this
+# as the "default":
+# * source fingerprints are accessed more frequently than contents (ie hrefs,
+#   urls, etc) so caching them can have nice affects on performance.  Plus it
+#   seems silly to have to compile the source file everytime you want to get its
+#   href so you can link it in.
+# * fingerprints have a much smaller data size so won't overly bloat memory.
+
+class Dassets::DefaultCache
+
+  def initialize
+    @hash = {}
+    @write_mutex = ::Mutex.new
+  end
+
+  def keys;    @hash.keys; end
+  def [](key); @hash[key]; end
+
+  def []=(key, value)
+    @write_mutex.synchronize do
+      @hash[key] = value if key =~ /-- fingerprint$/ # only write fingerprint keys
+    end
+  end
+
+end
+

data/lib/dassets/digest_cmd.rb

@@ -0,0 +1,36 @@
+require 'fileutils'
+require 'dassets'
+require 'dassets/source_file'
+
+module Dassets; end
+class Dassets::DigestCmd
+
+  attr_reader :paths
+
+  def initialize(abs_paths)
+    @paths = abs_paths || []
+  end
+
+  def run(io=nil)
+    files = @paths
+    if @paths.empty?
+      # always get the latest source list
+      files = Dassets::SourceList.new(Dassets.config)
+    end
+
+    log io, "digesting #{files.count} source file(s) ..."
+    digest_the_files(files)
+  end
+
+  private
+
+  def digest_the_files(files)
+    files.each{ |f| Dassets::SourceFile.new(f).asset_file.digest! }
+  end
+
+  def log(io, msg)
+    io.puts msg if io
+  end
+
+end
+

data/lib/dassets/engine.rb

@@ -19,7 +19,6 @@ module Dassets
   end
 
   class NullEngine < Engine
-
     def ext(input_ext)
       input_ext
     end
@@ -27,7 +26,6 @@ module Dassets
     def compile(input)
       input
     end
-
   end
 
 end

data/lib/dassets/file_store.rb

@@ -0,0 +1,36 @@
+require 'thread'
+require 'dassets/root_path'
+
+module Dassets; end
+class Dassets::FileStore
+  attr_reader :root
+
+  def initialize(root)
+    @root = Dassets::RootPath.new(root)
+    @save_mutex = ::Mutex.new
+  end
+
+  def save(url, &block)
+    @save_mutex.synchronize do
+      store_path(url).tap do |path|
+        FileUtils.mkdir_p(File.dirname(path))
+        File.open(path, "w"){ |f| f.write(block.call) }
+      end
+    end
+  end
+
+  def store_path(url)
+    File.join(@root, url)
+  end
+
+end
+
+class Dassets::NullFileStore < Dassets::FileStore
+  def initialize
+    super('')
+  end
+
+  def save(url, &block)
+    store_path(url) # no-op, just return the store path like the base does
+  end
+end

data/lib/dassets/runner.rb

@@ -20,16 +20,9 @@ class Dassets::Runner
 
     case @cmd_name
     when 'digest'
-      require 'dassets/cmds/digest_cmd'
+      require 'dassets/digest_cmd'
       abs_paths = @cmd_args.map{ |path| File.expand_path(path, @pwd) }
-      Dassets::Cmds::DigestCmd.new(abs_paths).run($stdout)
-    when 'cache'
-      require 'dassets/cmds/cache_cmd'
-      cache_root_path = File.expand_path(@cmd_args.first, @pwd)
-      unless cache_root_path && File.directory?(cache_root_path)
-        raise CmdError, "specify an existing cache directory"
-      end
-      Dassets::Cmds::CacheCmd.new(cache_root_path).run($stdout)
+      Dassets::DigestCmd.new(abs_paths).run($stdout)
     when 'null'
       NullCommand.new.run
     else

data/lib/dassets/server/request.rb

@@ -14,10 +14,10 @@ class Dassets::Server
     # Determine if the request is for an asset file
     # This will be called on every request so speed is an issue
     # - first check if the request is a GET or HEAD (fast)
-    # - then check if for a digest resource (kinda fast)
-    # - then check if on a path in the digests (slower)
+    # - then check if for a digested asset resource (kinda fast)
+    # - then check if source exists for the digested asset (slower)
     def for_asset_file?
-      !!((get? || head?) && for_digest_file? && Dassets.digests[asset_path])
+      !!((get? || head?) && for_digested_asset? && asset_file.source_cache.exists?)
     end
 
     def asset_path
@@ -30,8 +30,8 @@ class Dassets::Server
 
     private
 
-    def for_digest_file?
-      !path_digest_match.nil?
+    def for_digested_asset?
+      !path_digest_match.captures.empty?
     end
 
     def path_digest_match

data/lib/dassets/source_cache.rb

@@ -0,0 +1,39 @@
+require 'dassets/source_file'
+
+module Dassets; end
+class Dassets::SourceCache
+
+  attr_reader :digest_path, :source_file, :cache
+
+  def initialize(digest_path, cache=nil)
+    @digest_path = digest_path
+    @source_file = Dassets::SourceFile.find_by_digest_path(digest_path)
+    @cache = cache || NoCache.new
+  end
+
+  def content
+    @cache["#{self.key} -- content"] ||= @source_file.compiled
+  end
+
+  def fingerprint
+    @cache["#{self.key} -- fingerprint"] ||= @source_file.fingerprint
+  end
+
+  def key
+    "#{self.digest_path} -- #{self.mtime}"
+  end
+
+  def mtime
+    @source_file.mtime
+  end
+
+  def exists?
+    @source_file.exists?
+  end
+
+  class NoCache
+    def [](key); end
+    def []=(key, value); end
+  end
+
+end