helium 0.1.0

data/lib/helium/jake.rb

@@ -0,0 +1,73 @@
+# This file is loaded by Jake for projects created using the Helium command
+# line tools. It copies build files into the test directory and generates a
+# JS.Packages file for the project so that the user can test that their
+# dependencies are correctly configured.
+
+module Helium
+  module JakeBuildHelper
+    
+    LIB = 'lib'
+
+    TEST_DIR   = File.join(PROJECT_DIR, 'test')
+    PUBLIC_DIR = File.join(TEST_DIR, 'public')
+
+    # If test/public exists, we generate files there. Otherwise
+    # we just put generated files in the test directory.
+    TARGET_DIR = File.directory?(PUBLIC_DIR) ? PUBLIC_DIR : TEST_DIR
+    LIB_DIR    = File.join(TARGET_DIR, LIB)
+
+    PACKAGES = ERB.new(<<-EOS, nil, '-')
+// This file is automatically generated when you run `jake`. You should
+// keep it out of your version control system.
+
+// Maintain your project's dependencies in jake.yml; they will be
+// reflected here when you run a build.
+
+JS.Packages(function() { with(this) {
+<% files.each do |path, meta| %>
+    file('./<%= LIB %><%= path %>')
+        .provides(<%= list(meta[:provides]) %>)
+        .requires(<%= list(meta[:requires]) %>)
+        .uses(<%= list(meta[:uses]) %>);
+<% end -%>
+}});
+    EOS
+
+    def self.list(array)
+      (array || []).map { |s| s.inspect } * ', '
+    end
+
+    def self.short_path(path)
+      path.sub(PROJECT_DIR, '.')
+    end
+
+    files = {}
+
+    update = lambda do |build, package, build_type, path|
+      puts "created: #{path}"
+      files[path.sub(build.build_directory, '')] = package.meta if build_type == :min
+    end
+
+    jake_hook(:file_created,     &update)
+    jake_hook(:file_not_changed, &update)
+
+    jake_hook :build_complete do |build|
+      FileUtils.rm_rf(LIB_DIR) if File.exists?(LIB_DIR)
+      
+      files.each do |path, meta|
+        source = File.join(build.build_directory, path)
+        target = File.join(LIB_DIR, path)
+        FileUtils.mkdir_p(File.dirname(target))
+        puts "Copying #{ short_path(source) } --> #{ short_path(target) }"
+        FileUtils.cp(source, target)
+      end
+      
+      packages = PACKAGES.result(binding)
+      pkg_file = File.join(TARGET_DIR, 'packages.js')
+      puts "Writing package listing to #{ short_path(pkg_file) }"
+      File.open(pkg_file, 'w') { |f| f.write(packages) }
+    end
+    
+  end
+end
+

data/lib/helium/logger.rb

@@ -0,0 +1,15 @@
+module Helium
+  # Class to pick up log messages from the build process so we can display
+  # them elsewhere, e.g. in web pages after deploy requests.
+  class Logger
+    attr_reader :messages
+    def initialize
+      @messages = []
+    end
+    
+    def update(type, msg)
+      @messages << msg
+    end
+  end
+end
+

data/lib/helium/trie.rb

@@ -0,0 +1,59 @@
+module Helium
+  class Trie
+    include Enumerable
+    attr_accessor :value
+    
+    def initialize(value = nil)
+      @value = value
+      @children = {}
+    end
+    
+    def each_child(&block)
+      @children.keys.sort.each { |key| block.call(key, @children[key]) }
+    end
+    
+    def each(key = [], &block)
+      each_child { |prefix, trie| trie.each(key + [prefix], &block) }
+      block.call(key, @value) unless @value.nil?
+    end
+    
+    def has_key?(key)
+      trie = traverse(key)
+      trie and not trie.value.nil?
+    end
+    
+    def [](key)
+      trie = traverse(key)
+      trie ? trie.value : nil
+    end
+    
+    def []=(key, value)
+      traverse(key, true).value = value
+    end
+    
+    def traverse(key, create_if_absent = false)
+      key = convert_key(key)
+      return self if key.empty?
+      trie = @children[key.first]
+      return nil if trie.nil? and not create_if_absent
+      trie = @children[key.first] = Trie.new if trie.nil?
+      trie.traverse(key[1..-1], create_if_absent)
+    end
+    
+    def inspect
+      @children.inspect
+    end
+    
+  private
+    
+    def convert_key(key)
+      case key
+      when Array      then key
+      when Symbol     then key.to_s.split('')
+      when String     then key.split('')
+      when Enumerable then key.entries
+      end
+    end
+  end
+end
+

data/lib/helium/views/deploy.erb

@@ -0,0 +1,13 @@
+<%if @log %>
+  <h2>Deploy logs</h2>
+  <ul class="logs">
+  <% @log.each do |msg| %>
+    <li><%=h msg %></li>
+  <% end %>
+  </ul>
+  
+<% elsif @error %>
+  <h2>Deployment error</h2>
+  <p class="error"><%=h @error %></p>
+<% end %>
+

data/lib/helium/views/edit.erb

@@ -0,0 +1,11 @@
+<h2>Edit: <%=h File.basename(@file) %></h2>
+
+<% if @error %>
+  <p class="error"><%=h @error %></p>
+<% end %>
+
+<form action="/app/<%=h @action %>" method="post">
+  <textarea name="contents" <%= disabled? %>><%=h @contents %></textarea>
+  <input type="submit" value="Save" <%= disabled? %>>
+</form>
+

data/lib/helium/views/index.erb

@@ -0,0 +1,67 @@
+<h2>Helium, the JavaScript package server</h2>
+
+<p>Helium hosts versioned copies of JavaScript libraries checked out from Git,
+and lets you load objects from these libraries on demand. It uses
+<a href="http://github.com/jcoglan/jake">Jake</a> to build each library and extract
+dependency data, and <a href="http://jsclass.jcoglan.com/packages.html">JS.Packages</a>
+to resolve dependencies and load files at runtime. The
+<a href="/<%= Helium::WEB_ROOT %>/<%= Helium::PACKAGES %>">package manifest</a> is
+generated using data extracted during the build process.</p>
+
+<p>To use libraries from this server, drop the following in your <code>HEAD</code>:</p>
+
+<pre class="prettyprint">&lt;script src="http://<%= @location %>/<%= Helium::PACKAGES_MIN %>"
+        type="text/javascript">&lt;/script>
+
+&lt;script type="text/javascript">
+// Specify which branch/tag of each Git project to use, e.g.
+// Helium.use('yui', '2.7.0');
+// Helium.use('ojay', '0.4.1');
+&lt;/script></pre>
+
+<p>Use the <code>require()</code> function throughout your pages to load JavaScript
+objects on demand. Dependencies are automatically handled for you:</p>
+
+<pre class="prettyprint">&lt;script type="text/javascript">
+require('GMap2', 'YAHOO.util.Selector', function() {
+    
+    var box   = document.getElementById('mapview'),
+        map   = new GMap2(box),
+        links = YAHOO.util.Selector.query('a');
+});
+&lt;/script></pre>
+
+<p>To set up Helium, you&rsquo;ll need to <a href="/app/config">add projects to deploy</a>
+using YAML format. Each entry should be the name of a project followed by its Git URL.
+Helium relies on JS.Class, for which you need to set a Git URL and a version to use:</p>
+
+<pre>---
+js.class:
+  repository:       git://github.com/jcoglan/js.class.git
+  version:          2.1.x
+
+projects:
+  your-library:     git://github.com/your/library.git</pre>
+
+<p>You may also want to <a href="/app/custom">add some custom loaders</a> for libraries
+not deployed using Helium. For example the following are loaders for Google Maps:</p>
+
+<pre class="prettyprint">/**
+ * Loads the `google.load` function, required to load other
+ * parts of the Google API. Requires `Helium.GOOGLE_API_KEY`
+ * to be set beforehand.
+ **/
+loader(function(cb) {
+    var url = 'http://www.google.com/jsapi?key=' + Helium.GOOGLE_API_KEY;
+    load(url, cb);
+})  .provides('google.load');
+
+/**
+ * Loads the Google Maps API. Requires `Helium.GOOGLE_API_KEY`
+ * to be set beforehand.
+ **/
+loader(function(cb) { google.load('maps', '2.x', {callback: cb}) })
+    .provides('GMap2', 'GClientGeocoder',
+              'GEvent', 'GLatLng', 'GMarker')
+    .requires('google.load');</pre>
+

data/lib/helium/views/layout.erb

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+  <meta http-equiv="Content-type" content="text/html; charset=utf-8">
+  <title>Helium</title>
+  <link rel="stylesheet" href="/style.css" type="text/css" media="screen">
+  <link rel="stylesheet" href="/prettify.css" type="text/css" media="screen">
+  <script src="/prettify.js" type="text/javascript"></script>
+</head>
+<body onload="prettyPrint()">
+<div class="container">
+
+  <div class="header">
+    <h1><a href="/" class="logo"><%= logotype %></a>
+      <span class="tagline">Git-backed JavaScript deployment</span></h1>
+    
+    <ul class="navigation">
+      <li>
+        <h3><a href="/app/config">Edit configuration</a></h3>
+        <p>Register libraries using their Git URL to have Helium deploy them.</p>
+      </li>
+      <li>
+        <h3><a href="/app/custom">Custom loaders</a></h3>
+        <p>Add custom loader code for libraries from outside Helium.</p>
+      </li>
+    </ul>
+    <div class="clear"></div>
+  </div>
+  
+  <form action="/app/deploy" method="post">
+    <% unless @projects.empty? %>
+      <ul class="projects">
+      <% @projects.keys.sort.each_with_index do |name, i| %>
+        <li>
+          <input type="hidden" name="projects[<%=h name %>]" value="0">
+          <input type="checkbox" class="checkbox" name="projects[<%=h name %>]" id="projects_<%=h name %>" value="1">
+          <label for="projects_<%=h name %>"><%=h name %></label>
+        </li>
+      <% end %>
+      </ul>
+      <input type="submit" value="Deploy" <%= disabled? %>>
+    <% end %>
+  </form>
+  
+  <div class="main">
+    <%= yield %>
+  </div>
+  
+  <div class="clear"></div>
+  <div class="footer">
+    <p class="logo"><%= logotype %></p>
+    &copy; 2009 <a href="http://othermedia.com">theOTHERmedia</a>. Source code is
+    <a href="http://github.com/othermedia/helium">hosted on GitHub</a>.
+  </div>
+
+</div>
+</body>
+</html>
+

data/lib/helium/views/missing.erb

@@ -0,0 +1,6 @@
+<h2>Missing file: <code><%=h @path %></code></h2>
+
+<p>The file <code><%=h @path %></code> could not be found. If you expected this
+file to exist, you probably need to run the <code>Deploy</code> script: try the
+button over on the left.</p>
+

data/lib/helium/web.rb

@@ -0,0 +1,119 @@
+require 'fileutils'
+require 'rubygems'
+require 'sinatra/base'
+require 'yaml'
+
+module Helium
+  class Web < Sinatra::Base
+    
+    
+    ROOT_DIR = File.dirname(__FILE__)
+    require File.join(ROOT_DIR, '..', 'helium')
+    require File.join(ROOT_DIR, 'web_helpers')
+    
+    extend Configurable
+    
+    LIB_DIR  = 'lib'
+    
+    CONFIG   = File.join(APP_DIR, 'deploy.yml')
+    CUSTOM   = File.join(APP_DIR, 'custom.js')
+    PUBLIC   = File.join(APP_DIR, 'public', WEB_ROOT)
+    LOCK     = File.join(APP_DIR, '.lock')
+    
+    set :static, true
+    set :public, File.join(APP_DIR, 'public')
+    set :views, File.join(ROOT_DIR, 'views')
+    
+    before do
+      @projects = project_config
+      @domain   = env['HTTP_HOST']
+      @location = @domain + '/' + Helium::WEB_ROOT
+    end
+    
+    ## Home page -- just loads the project list and renders.
+    get('/') { erb :index }
+    
+    ## Rendered if a missing script file is requested.
+    get "/#{WEB_ROOT}/*" do
+      @path = params[:splat].first
+      halt 404, erb(:missing)
+    end
+    
+    ## Deploys all selected projects and renders a list of log messages.
+    post '/app/deploy' do
+      if not allow_write_access?(env)
+        @error = 'You are not authorized to run deployments'
+      elsif locked?
+        @error = 'Deployment already in progress'
+      end
+      
+      halt(200, erb(:deploy)) if @error
+      
+      with_lock do
+        deployer = Helium::Deployer.new(APP_DIR, LIB_DIR)
+        logger   = Helium::Logger.new
+        deployer.add_observer(logger)
+        
+        params[:projects].each do |name, value|
+          next unless value == '1'
+          deployer.deploy!(name, false)
+        end
+        
+        deployer.cleanup!
+        
+        custom = File.file?(CUSTOM) ? File.read(CUSTOM) : nil
+        files = deployer.run_builds!(:custom => custom, :domain => @domain)
+        
+        FileUtils.rm_rf(PUBLIC) if File.exists?(PUBLIC)
+        
+        files.each do |path|
+          source, dest = File.join(deployer.static_dir, path), File.join(PUBLIC, path)
+          FileUtils.mkdir_p(File.dirname(dest))
+          FileUtils.cp(source, dest)
+        end
+        
+        @log = logger.messages.map { |msg| msg.sub(File.join(APP_DIR, LIB_DIR), '') }
+        erb :deploy
+      end
+    end
+    
+    get('/app/config') { view_file :config }
+    
+    ## Save changes to the configuration file, making sure it validates as YAML.
+    post '/app/config' do
+      @action   = 'config'
+      @file     = CONFIG
+      @contents = params[:contents]
+      if allow_write_access?(env)
+        begin
+          data = YAML.load(@contents)
+          raise 'invalid' unless Hash === data
+          File.open(@file, 'w') { |f| f.write(@contents) }
+        rescue
+          @error = 'File not saved: invalid YAML'
+        end
+      else
+        @error = 'You are not authorized to edit this file'
+      end
+      @projects = project_config
+      erb :edit
+    end
+    
+    get('/app/custom') { view_file :custom }
+    
+    ## Save changes to the custom loaders file.
+    post '/app/custom' do
+      @action   = 'custom'
+      @file     = CUSTOM
+      @contents = params[:contents]
+      if allow_write_access?(env)
+        File.open(@file, 'w') { |f| f.write(@contents) }
+      else
+        @error = 'You are not authorized to edit this file'
+      end
+      erb :edit
+    end
+    
+  end
+end
+

data/lib/helium/web_helpers.rb

@@ -0,0 +1,65 @@
+module Helium
+  class Web
+    
+    helpers do
+      # Returns the data structure contained in the app's deploy.yml file.
+      def project_config
+        Helium::Deployer.new(File.dirname(CONFIG)).projects
+      end
+      
+      # Returns the list of IP addresses that have write access to the app.
+      def allowed_ips
+        Helium::Web.config.allow_ips
+      end
+      
+      # Returns +true+ iff the request should be allowed write access.
+      def allow_write_access?(env)
+        return true unless allowed_ips.is_a?(Array)
+        ip = (env['REMOTE_ADDR'] || '').scan(/(?:\d{1,3}\.){3}\d{1,3}/).flatten.first
+        allowed_ips.include?(ip)
+      end
+      
+      # Returns +true+ if a lock exists stopping other deploy processes running.
+      def locked?
+        File.file?(LOCK)
+      end
+      
+      # Places a lock in the filesystem while running a code block. This is
+      # used to make sure no more than one deploy process runs at once.
+      def with_lock(&block)
+        File.open(LOCK, 'w') { |f| f.write(Time.now.to_s) }
+        at_exit { File.delete(LOCK) if File.exists?(LOCK) }
+        result = block.call
+        File.delete(LOCK) if File.exists?(LOCK)
+        result
+      end
+      
+      # Generic handler for displaying editable files requested using GET.
+      def view_file(name)
+        @error    = 'You are not authorized to edit this file' unless allow_write_access?(env)
+        @projects = project_config
+        @action   = name.to_s
+        @file     = Helium::Web.const_get(name.to_s.upcase)
+        @contents = File.file?(@file) ? File.read(@file) : ''
+        erb :edit
+      end
+      
+      # Markup for the web UI's logo
+      def logotype
+        '<span class="symbol">He</span>lium'
+      end
+      
+      # Shorthand for ERB's HTML-escaping method
+      def h(string)
+        ERB::Util.h(string)
+      end
+      
+      # Returns a disabled attribute if one is required
+      def disabled?
+        allow_write_access?(env) ? '' : 'disabled="disabled"'
+      end
+    end
+    
+  end
+end
+