pinion 0.1.0

data/README.md

@@ -0,0 +1,78 @@
+Pinion
+======
+
+Pinion is a Rack application that serves assets, possibly transforming them in the process. It is generally
+useful for serving Javascript and CSS, and things that compile to Javascript and CSS such as Coffeescript and
+Sass.
+
+Goals
+=====
+
+There are a lot of tools that accomplish very similar things in this space. Pinion is meant to be a very
+simple and lightweight solution. It is driven by these core goals (bold goals are implemented):
+
+* **Simple configuration and usage.**
+* **No added syntax to your assets (e.g. no `//= require my_other_asset`)**
+* **Recompile all compiled assets when they change (or dependencies change) in development and set mtimes**
+* Recompile asynchronously from requests (no polling allowed)
+* Compile assets one time in production
+
+Installation
+============
+
+    $ gem install pinion
+
+Usage
+=====
+
+The easiest way to use Pinion is to map your desired asset mount point to a `Pinion::Server` instance in your
+`config.ru`.
+
+``` ruby
+require "pinion"
+require "your_app.rb"
+
+map "/assets" do
+  server = Pinion::Server.new
+  # Tell Pinion each type of conversion it should perform
+  server.convert :scss => :css # Sass and Coffeescript will just work if you have the gems installed
+  server.convert :coffee => :js # Conversion types correspond to file extensions. .coffee -> .js
+  server.convert :styl => :css do |file_contents|
+    Stylus.compile file_contents # Requires the stylus gem
+  end
+  # Tell Pinion the paths to watch
+  server.watch "public/javascripts"
+  server.watch "public/scss"
+  server.watch "public/stylus"
+  # Boom
+  run server
+end
+
+map "/" do
+  run Your::App.new
+end
+```
+
+Notes
+-----
+
+* Everything in `/assets` (in the example) will be served as-is. No conversions will be performed on those
+  files (unless you add `/assets` as a watch path).
+* Currently, Pinion sidesteps the dependency question by invalidating its cache of each file of a particular
+  type (say, all `.scss` files) when any such source file is changed.
+* The order that paths are added to the watch list is a priority order in case of conflicting assets. (For
+  intance, if `foo/bar` and `foo/baz` are both on the watch list, and both of the files `foo/bar/style.scss`
+  and `foo/baz/style.scss` exist, then `foo/bar/style.scss` will be used if a request occurs for `/style.css`.
+
+You can see an example app using Pinion and Sinatra in the `example/` directory.
+
+Authors
+=======
+
+Pinion was written by Caleb Spare ([cespare](https://github.com/cespare)). Inspiration from
+[sprockets](https://github.com/sstephenson/sprockets) and [rerun](https://github.com/alexch/rerun).
+
+License
+=======
+
+Pinion is released under [the MIT License](http://www.opensource.org/licenses/mit-license.php).

data/lib/pinion/conversion.rb

@@ -0,0 +1,78 @@
+require "pinion/error"
+
+module Pinion
+  # A conversion describes how to convert certain types of files and create asset links for them.
+  # Conversions.create() provides a tiny DSL for defining new conversions
+  class Conversion
+    @@conversions = {}
+    def self.[](from_and_to) @@conversions[from_and_to] end
+    def self.conversions_for(to) @@conversions.values.select { |c| c.to_type == to } end
+    def self.create(from_and_to, &block)
+      unless from_and_to.is_a?(Hash) && from_and_to.size == 1
+        raise Error, "Unexpected argument to Conversion.create: #{from_and_to.inspect}"
+      end
+      conversion = Conversion.new *from_and_to.to_a[0]
+      conversion.instance_eval &block
+      conversion.verify
+      @@conversions[conversion.signature] = conversion
+    end
+
+    attr_reader :from_type, :to_type, :gem_required
+
+    def initialize(from_type, to_type)
+      @from_type = from_type
+      @to_type = to_type
+      @gem_required = nil
+      @conversion_fn = nil
+    end
+
+    # DSL methods
+    def require_gem(gem_name) @gem_required = gem_name end
+    def render(&block) @conversion_fn = block end
+
+    # Instance methods
+    def signature() { @from_type => @to_type } end
+    def content_type
+      case @to_type
+      when :css then "text/css"
+      when :js then "application/javascript"
+      else
+        raise Error, "No known content-type for #{@to_type}."
+      end
+    end
+    def convert(file_contents) @conversion_fn.call(file_contents) end
+    def require_dependency
+      return unless @gem_required
+      begin
+        require @gem_required
+      rescue LoadError => e
+        raise "Tried to load conversion for #{signature.inspect}, but failed to load the #{@gem_required} gem"
+      end
+    end
+
+    def verify
+      unless [@from_type, @to_type].all? { |s| s.is_a? Symbol }
+        raise Error, "Expecting symbol key/value but got #{from_and_to.inspect}"
+      end
+      unless @conversion_fn
+        raise Error, "Must provide a conversion function with convert { |file_contents| ... }."
+      end
+    end
+  end
+
+  # Define built-in conversions
+  Conversion.create :scss => :css do
+    require_gem "sass"
+    render { |file_contents|  Sass::Engine.new(file_contents, :syntax => :scss).render }
+  end
+
+  Conversion.create :sass => :css do
+    require_gem "sass"
+    render { |file_contents| Sass::Engine.new(file_contents, :syntax => :sass).render }
+  end
+
+  Conversion.create :coffee => :js do
+    require_gem "coffee-script"
+    render { |file_contents| CoffeeScript.compile(file_contents) }
+  end
+end

data/lib/pinion/error.rb

@@ -0,0 +1,3 @@
+module Pinion
+  class Error < RuntimeError; end
+end

data/lib/pinion/server.rb

@@ -0,0 +1,171 @@
+#require "fssm"
+
+require "pinion/error"
+require "pinion/conversion"
+require "time"
+require "set"
+
+module Pinion
+  class Server
+    #CachedFile = Struct.new :from_path, :to_path, :compiled_contents, :mtime
+    Asset = Struct.new :from_path, :to_path, :from_type, :to_type, :compiled_contents, :length, :mtime,
+                       :content_type
+    Watch = Struct.new :path, :from_type, :to_type, :conversion
+
+    def initialize
+      @running = false
+      @watch_directories = []
+      @watches = []
+      @cached_assets = {}
+      @conversions_used = Set.new
+    end
+
+    def convert(from_and_to, &block)
+      unless from_and_to.is_a?(Hash) && from_and_to.size == 1
+        raise Error, "Unexpected argument to convert: #{from_and_to.inspect}"
+      end
+      from, to = from_and_to.to_a[0]
+      unless [from, to].all? { |s| s.is_a? Symbol }
+        raise Error, "Expecting symbols in this hash #{from_and_to.inspect}"
+      end
+      if block_given?
+        # Save new conversion type (this might overwrite an implicit or previously defined conversion)
+        Conversion.create(from_and_to) do
+          render { |file_contents| block.call(file_contents) }
+        end
+      else
+        unless Conversion[from_and_to]
+          raise Error, "No immplicit conversion for #{from_and_to.inspect}. Must provide a conversion block."
+        end
+      end
+    end
+
+    def watch(path)
+      raise Error, "#{path} is not a directory." unless File.directory? path
+      @watch_directories << path
+    end
+
+    # Boilerplate mostly stolen from sprockets
+    # https://github.com/sstephenson/sprockets/blob/master/lib/sprockets/server.rb
+    def call(env)
+      puts "********************** CALLING CALL"
+      puts "\033[01;34m>>>> env['PATH_INFO']: #{env["PATH_INFO"].inspect}\e[m"
+      puts "************************************"
+      start unless @running
+
+      # Avoid modifying the session state, don't set cookies, etc
+      env["rack.session.options"] ||= {}
+      env["rack.session.options"].merge! :defer => true, :skip => true
+
+      path = env["PATH_INFO"].to_s.sub(%r[^/], "")
+
+      if path.include? ".."
+        return with_content_length([403, { "Content-Type" => "text/plain" }, ["Forbidden"]])
+      end
+
+      asset = get_asset(path)
+      if asset
+        headers = {
+          "Content-Type" => asset.content_type,
+          "Content-Length" => asset.length.to_s,
+          # TODO: set a long cache in prod mode when implemented
+          "Cache-Control" => "public, must-revalidate",
+          "Last-Modified" => asset.mtime.httpdate,
+        }
+        return [200, headers, []] if env["REQUEST_METHOD"] == "HEAD"
+        [200, headers, asset.compiled_contents]
+      else
+        with_content_length([404, { "Content-Type" => "text/plain" }, ["Not found"]])
+      end
+    rescue Exception => e
+      # TODO: logging
+      STDERR.puts "Error compiling #{path}:"
+      STDERR.puts "#{e.class.name}: #{e.message}"
+      # TODO: render nice custom errors in the browser
+      raise
+    end
+
+    private
+
+    def get_asset(to_path)
+      asset = @cached_assets[to_path]
+      if asset
+        mtime = asset.mtime
+        latest = latest_mtime_of_type(asset.from_type)
+        if latest > mtime
+          invalidate_all_assets_of_type(asset.from_type)
+          return get_asset(to_path)
+        end
+        puts "\033[01;34m>>>> Using cached asset at to_path: #{to_path.inspect}\e[m"
+      else
+        begin
+          asset = get_uncached_asset(to_path)
+        rescue Error
+          return nil
+        end
+        @cached_assets[to_path] = asset
+      end
+      asset
+    end
+
+    def latest_mtime_of_type(type)
+      latest = Time.at(0)
+      @watch_directories.each do |directory|
+        Dir[File.join(directory, "**/*.#{type}")].each do |file|
+          mtime = File.stat(file).mtime
+          latest = mtime if mtime > latest
+        end
+      end
+      latest
+    end
+
+    def get_uncached_asset(to_path)
+      from_path, conversion = find_source_file_and_conversion(to_path)
+      # If we reach this point we've found the asset we're going to compile
+      conversion.require_dependency unless @conversions_used.include? conversion
+      @conversions_used << conversion
+      # TODO: log at info: compiling asset ...
+      contents = conversion.convert(File.read(from_path))
+      length = File.stat(from_path).size
+      mtime = latest_mtime_of_type(conversion.from_type)
+      content_type = conversion.content_type
+      return Asset.new from_path, to_path, conversion.from_type, conversion.to_type,
+                       [contents], contents.length, mtime, content_type
+    end
+
+    def find_source_file_and_conversion(to_path)
+      path, dot, suffix = to_path.rpartition(".")
+      conversions = Conversion.conversions_for(suffix.to_sym)
+      raise Error, "No conversion for for #{to_path}" if conversions.empty?
+      @watch_directories.each do |directory|
+        conversions.each do |conversion|
+          Dir[File.join(directory, "#{path}.#{conversion.from_type}")].each do |from_path|
+            return [from_path, conversion]
+          end
+        end
+      end
+      raise Error, "No source file found for #{to_path}"
+    end
+
+    def invalidate_all_assets_of_type(type)
+      @cached_assets.delete_if { |to_path, asset| asset.from_type == type }
+    end
+
+    def with_content_length(response)
+      status, headers, body = response
+      [status, headers.merge({ "Content-Length" => Rack::Utils.bytesize(body).to_s }), body]
+    end
+
+    def update_asset(asset)
+    end
+
+    def start
+      @running = true
+      # TODO: mad threadz
+      # Start a thread with an FSSM watch on each directory. Upon detecting a change to a compiled file that
+      # is a dependency of any asset in @required_assets, call update_asset for each affected asset.
+      #
+      # There are some tricky threading issues here.
+    end
+  end
+end

data/lib/pinion/version.rb

@@ -0,0 +1,3 @@
+module Pinion
+  VERSION = "0.1.0"
+end

data/lib/pinion.rb

@@ -0,0 +1,2 @@
+require "pinion/version"
+require "pinion/server"

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: pinion
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Caleb Spare
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-27 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: &22405020 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *22405020
+description: ! 'Pinion is a Rack application that you can use to compile and serve
+  assets (such as Javascript and CSS).
+
+'
+email:
+- cespare@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/pinion/conversion.rb
+- lib/pinion/error.rb
+- lib/pinion/server.rb
+- lib/pinion/version.rb
+- lib/pinion.rb
+homepage: https://github.com/ooyala/pinion
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: pinion
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Pinion compiles and serves your assets
+test_files: []