foreman-capistrano 0.51.0

data/lib/foreman/process.rb

@@ -0,0 +1,102 @@
+require "foreman"
+require "rubygems"
+
+class Foreman::Process
+
+  attr_reader :command
+  attr_reader :env
+
+  # Create a Process
+  #
+  # @param [String] command  The command to run
+  # @param [Hash]   options
+  #
+  # @option options [String] :cwd (./)  Change to this working directory before executing the process
+  # @option options [Hash]   :env ({})  Environment variables to set for this process
+  #
+  def initialize(command, options={})
+    @command = command
+    @options = options.dup
+
+    @options[:env] ||= {}
+  end
+
+  # Run a +Process+
+  #
+  # @param [Hash] options
+  #
+  # @option options :env    ({})       Environment variables to set for this execution
+  # @option options :output ($stdout)  The output stream
+  #
+  # @returns [Fixnum] pid  The +pid+ of the process
+  #
+  def run(options={})
+    env    = options[:env] ? @options[:env].merge(options[:env]) : @options[:env]
+    output = options[:output] || $stdout
+
+    if Foreman.windows?
+      Dir.chdir(cwd) do
+        expanded_command = command.dup
+        env.each do |key, val|
+          expanded_command.gsub!("$#{key}", val)
+        end
+        Process.spawn env, expanded_command, :out => output, :err => output
+      end
+    elsif Foreman.jruby?
+      Dir.chdir(cwd) do
+        require "posix/spawn"
+        POSIX::Spawn.spawn env, command, :out => output, :err => output
+      end
+    elsif Foreman.ruby_18?
+      Dir.chdir(cwd) do
+        fork do
+          $stdout.reopen output
+          $stderr.reopen output
+          env.each { |k,v| ENV[k] = v }
+          exec command
+        end
+      end
+    else
+      Dir.chdir(cwd) do
+        Process.spawn env, command, :out => output, :err => output
+      end
+    end
+  end
+
+  # Send a signal to this +Process+
+  #
+  # @param [String] signal  The signal to send
+  #
+  def kill(signal)
+    if Foreman.windows?
+      pid && Process.kill(signal, pid)
+    else
+      pid && Process.kill("-#{signal}", pid)
+    end
+  rescue Errno::ESRCH
+    false
+  end
+
+  # Test whether or not this +Process+ is still running
+  #
+  # @returns [Boolean]
+  #
+  def alive?
+    kill(0)
+  end
+
+  # Test whether or not this +Process+ has terminated
+  #
+  # @returns [Boolean]
+  #
+  def dead?
+    !alive?
+  end
+
+private
+
+  def cwd
+    @options[:cwd] || "."
+  end
+
+end

data/lib/foreman/procfile.rb

@@ -0,0 +1,92 @@
+require "foreman"
+
+# Reads and writes Procfiles
+#
+# A valid Procfile entry is captured by this regex:
+#
+#   /^([A-Za-z0-9_]+):\s*(.+)$/
+#
+# All other lines are ignored.
+#
+class Foreman::Procfile
+
+  # Initialize a Procfile
+  #
+  # @param [String] filename (nil)  An optional filename to read from
+  #
+  def initialize(filename=nil)
+    @entries = []
+    load(filename) if filename
+  end
+
+  # Yield each +Procfile+ entry in order
+  #
+  def entries(&blk)
+    @entries.each do |(name, command)|
+      yield name, command
+    end
+  end
+
+  # Retrieve a +Procfile+ command by name
+  #
+  # @param [String] name  The name of the Procfile entry to retrieve
+  #
+  def [](name)
+    @entries.detect { |n,c| name == n }.last
+  end
+
+  # Create a +Procfile+ entry
+  #
+  # @param [String] name     The name of the +Procfile+ entry to create
+  # @param [String] command  The command of the +Procfile+ entry to create
+  #
+  def []=(name, command)
+    delete name
+    @entries << [name, command]
+  end
+
+  # Remove a +Procfile+ entry
+  #
+  # @param [String] name  The name of the +Procfile+ entry to remove
+  #
+  def delete(name)
+    @entries.reject! { |n,c| name == n }
+  end
+
+  # Load a Procfile from a file
+  #
+  # @param [String] filename  The filename of the +Procfile+ to load
+  #
+  def load(filename)
+    @entries.replace parse(filename)
+  end
+
+  # Save a Procfile to a file
+  #
+  # @param [String] filename  Save the +Procfile+ to this file
+  #
+  def save(filename)
+    File.open(filename, 'w') do |file|
+      file.puts self.to_s
+    end
+  end
+
+  # Get the +Procfile+ as a +String+
+  #
+  def to_s
+    @entries.map do |name, command|
+      [ name, command ].join(": ")
+    end.join("\n")
+  end
+
+private
+
+  def parse(filename)
+    File.read(filename).split("\n").map do |line|
+      if line =~ /^([A-Za-z0-9_]+):\s*(.+)$/
+        [$1, $2]
+      end
+    end.compact
+  end
+
+end

data/lib/foreman/version.rb

@@ -0,0 +1,5 @@
+module Foreman
+
+  VERSION = "0.51.0"
+
+end

data/lib/foreman.rb

@@ -0,0 +1,23 @@
+require "foreman/version"
+
+module Foreman
+
+  class AppDoesNotExist < Exception; end
+
+  def self.runner
+    File.expand_path("../../bin/foreman-runner", __FILE__)
+  end
+
+  def self.jruby?
+    defined?(RUBY_PLATFORM) and RUBY_PLATFORM == "java"
+  end
+
+  def self.ruby_18?
+    defined?(RUBY_VERSION) and RUBY_VERSION =~ /^1\.8\.\d+/
+  end
+
+  def self.windows?
+    defined?(RUBY_PLATFORM) and RUBY_PLATFORM =~ /(win|w)32$/
+  end
+
+end

data/man/foreman.1

@@ -0,0 +1,244 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "FOREMAN" "1" "July 2012" "Foreman 0.51.0" "Foreman Manual"
+.
+.SH "NAME"
+\fBforeman\fR \- manage Procfile\-based applications
+.
+.SH "SYNOPSIS"
+\fBforeman start [process]\fR
+.
+.br
+\fBforeman run <command>\fR
+.
+.br
+\fBforeman export <format> [location]\fR
+.
+.SH "DESCRIPTION"
+Foreman is a manager for Procfile\-based applications\. Its aim is to abstract away the details of the Procfile format, and allow you to either run your application directly or export it to some other process management format\.
+.
+.SH "RUNNING"
+\fBforeman start\fR is used to run your application directly from the command line\.
+.
+.P
+If no additional parameters are passed, foreman will run one instance of each type of process defined in your Procfile\.
+.
+.P
+If a parameter is passed, foreman will run one instance of the specified application type\.
+.
+.P
+The following options control how the application is run:
+.
+.TP
+\fB\-c\fR, \fB\-\-concurrency\fR
+Specify the number of each process type to run\. The value passed in should be in the format \fBprocess=num,process=num\fR
+.
+.TP
+\fB\-e\fR, \fB\-\-env\fR
+Specify one or more \.env files to load
+.
+.TP
+\fB\-f\fR, \fB\-\-procfile\fR
+Specify an alternate Procfile to load, implies \fB\-d\fR at the Procfile root\.
+.
+.TP
+\fB\-p\fR, \fB\-\-port\fR
+Specify which port to use as the base for this application\. Should be a multiple of 1000\.
+.
+.TP
+\fB\-t\fR, \fB\-\-tmux\fR
+Runs the processes in a tmux session\. Creates one window for each process and an extra window containing the output of each window (requires gawk)\.
+.
+.P
+\fBforeman run\fR is used to run one\-off commands using the same environment as your defined processes\.
+.
+.SH "EXPORTING"
+\fBforeman export\fR is used to export your application to another process management format\.
+.
+.P
+An location to export can be passed as an argument\. This argument may be either required or optional depending on the export format\.
+.
+.P
+The following options control how the application is run:
+.
+.TP
+\fB\-a\fR, \fB\-\-app\fR
+Use this name rather than the application\'s root directory name as the name of the application when exporting\.
+.
+.TP
+\fB\-c\fR, \fB\-\-concurrency\fR
+Specify the number of each process type to run\. The value passed in should be in the format \fBprocess=num,process=num\fR
+.
+.TP
+\fB\-l\fR, \fB\-\-log\fR
+Specify the directory to place process logs in\.
+.
+.TP
+\fB\-p\fR, \fB\-\-port\fR
+Specify which port to use as the base for this application\. Should be a multiple of 1000\.
+.
+.TP
+\fB\-t\fR, \fB\-\-template\fR
+Specify an alternate template to use for creating export files\. See \fIhttps://github\.com/ddollar/foreman/tree/master/data/export\fR for examples\.
+.
+.TP
+\fB\-u\fR, \fB\-\-user\fR
+Specify the user the application should be run as\. Defaults to the app name
+.
+.SH "GLOBAL OPTIONS"
+These options control all modes of foreman\'s operation\.
+.
+.TP
+\fB\-d\fR, \fB\-\-directory\fR
+Specify an alternate application root\. This defaults to the directory containing the Procfile\.
+.
+.TP
+\fB\-e\fR, \fB\-\-env\fR
+Specify an alternate environment file\. You can specify more than one file by using: \fB\-\-env file1,file2\fR\.
+.
+.TP
+\fB\-f\fR, \fB\-\-procfile\fR
+Specify an alternate location for the application\'s Procfile\. This file\'s containing directory will be assumed to be the root directory of the application\.
+.
+.SH "EXPORT FORMATS"
+foreman currently supports the following output formats:
+.
+.IP "\(bu" 4
+bluepill
+.
+.IP "\(bu" 4
+inittab
+.
+.IP "\(bu" 4
+runit
+.
+.IP "\(bu" 4
+upstart
+.
+.IP "" 0
+.
+.SH "INITTAB EXPORT"
+Will export a chunk of inittab\-compatible configuration:
+.
+.IP "" 4
+.
+.nf
+
+# \-\-\-\-\- foreman example processes \-\-\-\-\-
+EX01:4:respawn:/bin/su \- example \-c \'PORT=5000 bundle exec thin start >> /var/log/web\-1\.log 2>&1\'
+EX02:4:respawn:/bin/su \- example \-c \'PORT=5100 bundle exec rake jobs:work >> /var/log/job\-1\.log 2>&1\'
+# \-\-\-\-\- end foreman example processes \-\-\-\-\-
+.
+.fi
+.
+.IP "" 0
+.
+.SH "UPSTART EXPORT"
+Will create a series of upstart scripts in the location you specify\. Scripts will be structured to make the following commands valid:
+.
+.P
+\fBstart appname\fR
+.
+.P
+\fBstop appname\-processname\fR
+.
+.P
+\fBrestart appname\-processname\-3\fR
+.
+.SH "PROCFILE"
+A Procfile should contain both a name for the process and the command used to run it\.
+.
+.IP "" 4
+.
+.nf
+
+web: bundle exec thin start
+job: bundle exec rake jobs:work
+.
+.fi
+.
+.IP "" 0
+.
+.P
+A process name may contain letters, numbers amd the underscore character\. You can validate your Procfile format using the \fBcheck\fR command:
+.
+.IP "" 4
+.
+.nf
+
+$ foreman check
+.
+.fi
+.
+.IP "" 0
+.
+.SH "ENVIRONMENT"
+If a \fB\.env\fR file exists in the current directory, the default environment will be read from it\. This file should contain key/value pairs, separated by \fB=\fR, with one key/value pair per line\.
+.
+.IP "" 4
+.
+.nf
+
+FOO=bar
+BAZ=qux
+.
+.fi
+.
+.IP "" 0
+.
+.SH "DEFAULT OPTIONS"
+If a \fB\.foreman\fR file exists in the current directory, default options will be read from it\. This file should be in YAML format with the long option name as keys\. Example:
+.
+.IP "" 4
+.
+.nf
+
+concurrency: alpha=0,bravo=1
+port: 15000
+.
+.fi
+.
+.IP "" 0
+.
+.SH "EXAMPLES"
+Start one instance of each process type, interleave the output on stdout:
+.
+.IP "" 4
+.
+.nf
+
+$ foreman start
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Export the application in upstart format:
+.
+.IP "" 4
+.
+.nf
+
+$ foreman export upstart /etc/init
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Run one process type from the application defined in a specific Procfile:
+.
+.IP "" 4
+.
+.nf
+
+$ foreman start alpha \-p ~/myapp/Procfile
+.
+.fi
+.
+.IP "" 0
+.
+.SH "COPYRIGHT"
+Foreman is Copyright (C) 2010 David Dollar \fIhttp://daviddollar\.org\fR

data/spec/foreman/cli_spec.rb

@@ -0,0 +1,87 @@
+require "spec_helper"
+require "foreman/cli"
+
+describe "Foreman::CLI", :fakefs do
+  subject { Foreman::CLI.new }
+
+  describe ".foreman" do
+    before { File.open(".foreman", "w") { |f| f.puts "formation: alpha=2" } }
+
+    it "provides default options" do
+      subject.send(:options)["formation"].should == "alpha=2"
+    end
+
+    it "is overridden by options at the cli" do
+      subject = Foreman::CLI.new([], :formation => "alpha=3")
+      subject.send(:options)["formation"].should == "alpha=3"
+    end
+  end
+
+  describe "start" do
+    describe "when a Procfile doesnt exist", :fakefs do
+      it "displays an error" do
+        mock_error(subject, "Procfile does not exist.") do
+          dont_allow.instance_of(Foreman::Engine).start
+          subject.start
+        end
+      end
+    end
+
+    describe "with a valid Procfile" do
+      it "can run a single command" do
+        without_fakefs do
+          output = foreman("start env -f #{resource_path("Procfile")}")
+          output.should     =~ /env.1/
+          output.should_not =~ /test.1/
+        end
+      end
+
+      it "can run all commands" do
+        without_fakefs do
+          output = foreman("start -f #{resource_path("Procfile")} -e #{resource_path(".env")}")
+          output.should =~ /echo.1 \| echoing/
+          output.should =~ /env.1  \| bar/
+          output.should =~ /test.1 \| testing/
+        end
+      end
+    end
+  end
+
+  describe "check" do
+    it "with a valid Procfile displays the jobs" do
+      write_procfile
+      foreman("check").should == "valid procfile detected (alpha, bravo)\n"
+    end
+
+    it "with a blank Procfile displays an error" do
+      FileUtils.touch "Procfile"
+      foreman("check").should == "ERROR: no processes defined\n"
+    end
+
+    it "without a Procfile displays an error" do
+      FileUtils.rm_f "Procfile"
+      foreman("check").should == "ERROR: Procfile does not exist.\n"
+    end
+  end
+
+  describe "run" do
+    it "can run a command" do
+      forked_foreman("run echo 1").should == "1\n"
+    end
+
+    it "includes the environment" do
+      forked_foreman("run #{resource_path("bin/env FOO")} -e #{resource_path(".env")}").should == "bar\n"
+    end
+  end
+
+  describe "version" do
+    it "displays gem version" do
+      foreman("version").chomp.should == Foreman::VERSION
+    end
+
+    it "displays gem version on shortcut command" do
+      foreman("-v").chomp.should == Foreman::VERSION
+    end
+  end
+
+end

data/spec/foreman/engine_spec.rb

@@ -0,0 +1,104 @@
+require "spec_helper"
+require "foreman/engine"
+
+class Foreman::Engine::Tester < Foreman::Engine
+  attr_reader :buffer
+
+  def startup
+    @buffer = ""
+  end
+
+  def output(name, data)
+    @buffer += "#{name}: #{data}"
+  end
+
+  def shutdown
+  end
+end
+
+describe "Foreman::Engine", :fakefs do
+  subject do
+    write_procfile "Procfile"
+    Foreman::Engine::Tester.new.load_procfile("Procfile")
+  end
+
+  describe "initialize" do
+    describe "with a Procfile" do
+      before { write_procfile }
+
+      it "reads the processes" do
+        subject.process("alpha").command.should == "./alpha"
+        subject.process("bravo").command.should == "./bravo"
+      end
+    end
+  end
+
+  describe "start" do
+    it "forks the processes" do
+      mock(subject.process("alpha")).run(anything)
+      mock(subject.process("bravo")).run(anything)
+      mock(subject).watch_for_output
+      mock(subject).watch_for_termination
+      subject.start
+    end
+
+    it "handles concurrency" do
+      subject.options[:formation] = "alpha=2"
+      mock(subject.process("alpha")).run(anything).twice
+      mock(subject.process("bravo")).run(anything).never
+      mock(subject).watch_for_output
+      mock(subject).watch_for_termination
+      subject.start
+    end
+  end
+
+  describe "directories" do
+    it "has the directory default relative to the Procfile" do
+      write_procfile "/some/app/Procfile"
+      engine = Foreman::Engine.new.load_procfile("/some/app/Procfile")
+      engine.root.should == "/some/app"
+    end
+  end
+
+  describe "environment" do
+    it "should read env files" do
+      File.open("/tmp/env", "w") { |f| f.puts("FOO=baz") }
+      subject.load_env("/tmp/env")
+      subject.env["FOO"].should == "baz"
+    end
+
+    it "should read more than one if specified" do
+      File.open("/tmp/env1", "w") { |f| f.puts("FOO=bar") }
+      File.open("/tmp/env2", "w") { |f| f.puts("BAZ=qux") }
+      subject.load_env "/tmp/env1"
+      subject.load_env "/tmp/env2"
+      subject.env["FOO"].should == "bar"
+      subject.env["BAZ"].should == "qux"
+    end
+
+    it "should handle quoted values" do
+      File.open("/tmp/env", "w") do |f|
+        f.puts 'FOO=bar'
+        f.puts 'BAZ="qux"'
+        f.puts "FRED='barney'"
+        f.puts 'OTHER="escaped\"quote"'
+      end
+      subject.load_env "/tmp/env"
+      subject.env["FOO"].should   == "bar"
+      subject.env["BAZ"].should   == "qux"
+      subject.env["FRED"].should  == "barney"
+      subject.env["OTHER"].should == 'escaped"quote'
+    end
+
+    it "should fail if specified and doesnt exist" do
+      lambda { subject.load_env "/tmp/env" }.should raise_error(Errno::ENOENT)
+    end
+
+    it "should set port from .env if specified" do
+      File.open("/tmp/env", "w") { |f| f.puts("PORT=9000") }
+      subject.load_env "/tmp/env"
+      subject.send(:base_port).should == 9000
+    end
+  end
+
+end

data/spec/foreman/export/base_spec.rb

@@ -0,0 +1,19 @@
+require "spec_helper"
+require "foreman/engine"
+require "foreman/export"
+
+describe "Foreman::Export::Base", :fakefs do
+  let(:procfile) { FileUtils.mkdir_p("/tmp/app"); write_procfile("/tmp/app/Procfile") }
+  let(:location) { "/tmp/init" }
+  let(:engine)   { Foreman::Engine.new().load_procfile(procfile) }
+  let(:subject)  { Foreman::Export::Base.new(location, engine) }
+
+  it "has a say method for displaying info" do
+    mock(subject).puts("[foreman export] foo")
+    subject.send(:say, "foo")
+  end
+
+  it "raises errors as a Foreman::Export::Exception" do
+    lambda { subject.send(:error, "foo") }.should raise_error(Foreman::Export::Exception, "foo")
+  end
+end