git_wit 0.0.3 → 0.0.4.pre

data/README.md

@@ -5,99 +5,132 @@
 
 Dead simple Git hosting for Rails apps.
 
-## Quickstart
+## Crash Course
 
-Create a Rails 3.2 app if you don't already have one. Add `git_wit` to your
-Gemfile:
+Start hosting git repositories in seconds. Create a new Rails app and 
+install GitWit:
 
-```ruby
-# Use github for now - early development:
-gem "git_wit", git: "https://github.com/xdissent/git_wit.git"
+```console
+$ rails new example --skip-bundle; cd example       # New Rails app
+$ echo 'gem "git_wit"' >> Gemfile; bundle           # Install git_wit gem
+$ rails g git_wit:install insecure_auth insecure_write authenticate authorize_read authorize_write
+$ rails s -d  # <- Start Rails server               # ^- Install/config GitWit
+```
 
-# Later it might be safe to use a rubygems release:
-# gem "git_wit", "~> 0.1.0"
+That's it - your app is hosting git repositories. Create a repositories folder,
+init a bare repo, and push to it:
+
+```console
+$ git init
+$ git add .
+$ git commit -m "That was easy"
+$ mkdir repositories                                # Hosted repos folder
+$ git init --bare repositories/example.git          # Example bare repo
+$ git remote add origin http://localhost:3000/example.git
+$ git push origin master  # Push example app to itself to store in itself!
 ```
 
-Run `bundle install` followed by `rails g git_wit:install` and then checkout 
-[`config/initializers/git_wit.rb`](https://github.com/xdissent/git_wit/blob/master/lib/generators/git_wit/templates/git_wit.rb). 
-You'll want to first change `config.repositories_path` to a folder where you'd 
-like to store your repositories. Let's use "tmp/repositories" in our app root 
-for fun:
+HTTPS? That works too:
 
-```ruby
-config.repositories_path = Rails.root.join("tmp", "repositories").to_s
+```console
+$ sudo echo "pre-loading sudo so we can background tunnels in a moment"
+$ rails g git_wit:install authenticate authorize_read authorize_write -f
+$ gem install tunnels
+$ sudo tunnels 443 3000 &       # or `rvmsudo tunnels...` if using RVM
+$ git remote add https https://localhost/example.git
+$ GIT_SSL_NO_VERIFY=1 git push https master:https-master  # Trust yourself
 ```
 
-Normally you wouldn't want to allow users to send their authentication 
-credentials over an insecure protocol like HTTP, because they'll be sent in 
-plain text over the wire. And since anonymous write access is always disallowed,
-that means you can't safely push over HTTP without SSL. To disable these 
-protections, something you'd **never** do in a production environment, change
-the following config values in the initializer:
+Still not impressed? Try SSH (OS X only currently):
 
+```console
+$ rails g git_wit:install authenticate authorize_read authorize_write ssh_user:git_wit -f
+$ rails g git_wit:ssh_user      # Creates/configs git_wit SSH user
+$ rake git_wit:ssh:add_key      # Grant access for ~/.ssh/id_rsa.pub
+$ git remote add ssh git_wit@localhost:example.git
+$ git push ssh master:ssh-master
 ```
+
+You might want to get rid of that system user you just created:
+
+```console
+$ rails d git_wit:ssh_user
+```
+
+
+## Overview
+
+GitWit adds git hosting abilities to any Rails app. It provides configurable
+authentication and authorization methods that can be integrated with any 
+user/repository access model you'd like. All configuration is handled through a
+single initializer, 
+[`config/initializers/git_wit.rb`](https://github.com/xdissent/git_wit/blob/master/lib/generators/git_wit/templates/git_wit.rb). 
+Run `rails g git_wit:install` to generate a default configuration for 
+modification. All configuration details are contained within comments inside
+the initializer, or read on for the highlights.
+
+
+## Authentication
+
+Normally GitWit prevents the user from sending authentication credentials in
+plaintext (via HTTP without SSL). To disable these protections, something you'd 
+**never** do in a production environment, change the following config values 
+in the initializer:
+
+```ruby
 config.insecure_auth = true
 config.insecure_write = true
 ```
 
-Now let's set up some simple (fake) authentication and authorization:
+Authentication is handled by the `config.authenticate` attribute. A valid
+authenticator is any callable that accepts a user model instance and a 
+clear-text password. The authenticator should return a boolean response 
+indicating whether the user is authenticated for the given password. To allow
+any user as long as the password matches the username:
 
 ```ruby
 config.authenticate = ->(user, password) do
-  %w(reader writer).include?(user) && user == password
-end
-
-config.authorize_read = ->(user, repository) do
-  %w(reader writer).include?(user)
-end
-
-config.authorize_write = ->(user, repository) do
-  user == "writer"
+  user == password
 end
 ```
 
-What we've done is effectively create two users: `reader` and `writer`. Both can
-read all repositories, but only `writer` may write (and can write to any repo.)
-Both users are considered authenticated if the password matches the username.
-
-Now your app is ready to start serving git repos over HTTP. Just create the 
-repositories folder, initialize a repo and start the server:
+The user model is simply the username as a string by default. Before passing
+the user to the authenticator, GitWit will call `config.user_for_authenication`,
+passing it the username and expecting a new user model instance in return. For
+example:
 
-```console
-$ mkdir -p tmp/repositories
-$ git init --bare tmp/repositories/example.git
-$ rails s
+```ruby
+config.user_for_authentication = ->(username) do
+  User.active.find_by_login username: username
+end
 ```
 
-Clone your repo, make some changes, and push:
+Now the `config.authenticate` authenticator will recieve the `User` instance:
 
-```console
-$ git clone http://localhost:3000/example.git
-$ cd example
-$ touch README
-$ git add README
-$ git commit -m "First"
-$ git push origin master
+```ruby
+config.authenticate = ->(user, password) do
+  user.valid_password? password   # user is a User
+end
 ```
 
-Your server will ask you for a username and password when you push - use 
-`writer` for both and it should accept your changes.
 
+## Authorization
 
-## SSL
+Two configuration attributes are responsible for authorization: 
+`config.authorize_read` and `config.authorize_write`. They're passed the user 
+instance (already authenticated) and the repository path as a string. The 
+repository path is relative to `config.repositories_path` 
+(`<app root>/repositories` by default). The authorizers should return a boolean
+to grant or deny access accordingly. A simple example:
 
-You **really** should turn `insecure_auth` and `insecure_write` back to `false`
-as quickly as possible and enable SSL for read/write access. GitWit doesn't 
-need any special SSL configuration - just flip SSL on in whatever web server
-is running Rails. You can also use the 
-[tunnels](https://github.com/jugyo/tunnels) gem to run your app with SSL in 
-development. Just add it to the Gemfile and run `bundle install` followed by
-`sudo tunnels` (or `rvmsudo tunnels` for RVM). For `rails s`, which runs on
-port 3000 by default, run `sudo tunnels 443 3000`. Now you may clone 
-repositories over HTTPS:
+```ruby
+config.authorize_read = ->(user, repository) do
+  %w(reader writer).include?(user)
+end
 
-```console
-$ git clone https://localhost/example.git
+config.authorize_write = ->(user, repository) do
+  user == "writer"
+end
 ```
 
 
@@ -133,110 +166,25 @@ authenticating, the SSH user will `sudo` to the application user to continue
 with the git operation. This eliminates the need for all the bat-shit crazy git
 pulls/pushes and SSH wrappers and crap that are typical of gitolite/gitosis
 setups. Your application user owns everything except the `authorized_keys` file
-and the `ssh_user` only needs to know how to call the `gw-shell` command.
+and the `ssh_user` only needs to know how to call the `git_wit git-shell` 
+command.
 
-First, create a dedicated SSH user. On Mountain Lion:
-
-```console
-$ sudo dscl . -create /Groups/gitwit
-$ sudo dscl . -create /Groups/gitwit PrimaryGroupID 333
-$ sudo dscl . -create /Groups/gitwit RealName "GitWit Server"
-$ sudo dscl . -create /Users/gitwit UniqueID 333
-$ sudo dscl . -create /Users/gitwit PrimaryGroupID 333
-$ sudo dscl . -create /Users/gitwit NFSHomeDirectory /var/gitwit
-$ sudo dscl . -create /Users/gitwit UserShell /bin/bash
-$ sudo dscl . -create /Users/gitwit RealName "GitWit Server"
-$ sudo mkdir -p ~gitwit
-$ sudo chown -R gitwit:gitwit ~gitwit
-```
-
-Enable the `ssh_user` config value in `config/initializers/git_wit.rb`:
+GitWit comes with an initializer to set everything up for you. First, enable the 
+`ssh_user` config in `config/initializers/git_wit.rb`:
 
 ```ruby
-config.ssh_user = "gitwit"
-```
-
-Now your application user needs to be allowed to `sudo` as `ssh_user` and vice
-versa. Edit `/etc/sudoers` using `sudo visudo` and add the following lines:
-
-```
-rails_user ALL=(gitwit) NOPASSWD:ALL
-gitwit ALL=(rails_user) NOPASSWD:ALL
-```
-
-Replace `rails_user` with the application under which your Rails app runs, which
-will be your personal username if using `rails s` or Pow.
-
-Test your `sudo` rights and initialize the `ssh_user` environment:
-
-```console
-$ sudo -u gitwit -i
-$ mkdir .ssh
-$ chmod 700 .ssh
-$ touch .ssh/authorized_keys
-$ chmod 600 .ssh/authorized_keys
-```
-
-If you're using RVM or some other wacky environment manipulating tool, you're 
-going to want to adjust the login environment for `ssh_user` by creating a
-`~ssh_user/.bashrc` file. For example, to load a specific RVM gemset:
-
-```bash
-source "/Users/xdissent/.rvm/environments/ruby-1.9.3-p385@git_wit"
+config.ssh_user = "git_wit"
 ```
 
-You may also need to adjust the `PATH` to include the location of the `gw-shell`
-executable. If you're using `bundle --binstubs` for example:
-
-```bash
-export PATH="/path/to/app/bin:$PATH"
-```
-
-The `gw-shell` command handles the authentication and authorization for the SSH
-protocol. It is initially called by `ssh_user` upon login (git operation) and it
-will attempt to `sudo` to the application user and re-run itself with the same
-environment. It determines which user is the "application user" by looking at
-who owns the rails app root folder. To determine where the app root is actually
-located, it looks for the ENV variables `RAILS_ROOT` and `BUNDLE_GEMFILE` in 
-order. When in doubt, set `RAILS_ROOT` in `~ssh_user/.bashrc`:
-
-```bash
-export RAILS_ROOT="/path/to/app"
-```
-
-**Remember to add `export RAILS_ENV="production"` for production deployments!**
-
-You can easily sanity check your environment using `sudo` as your app user:
+Now run the initializer:
 
 ```console
-$ sudo -u gitwit -i
-$ source .bashrc
-$ which gw-shell
-/Users/xdissent/Code/git_wit/stubs/gw-shell
-$ echo $RAILS_ROOT
-/Users/xdissent/Code/git_wit/test/dummy
+$ rails g git_wit:ssh_user
 ```
 
-Now all that's left to do is add some `authorized_keys` and you're all set. 
-This can be done from the rails console (`rails c`):
-
-```ruby
-GitWit.add_authorized_key "writer", "ssh-rsa long-ass-key-string writer@example.com"
-# => nil 
-GitWit.authorized_keys_file.keys
-# => [command="gw-shell writer",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa long-ass-key-string writer@example.com] 
-```
-
-You may now clone/push/pull over SSH - assuming the key you installed for 
-`writer` is known to your ssh agent (ie `~/.ssh/id_rsa`):
-
-```console
-$ git clone gitwit@localhost:example.git
-```
+To add a public key: `rake git_wit:ssh:add_key`
 
-See the dummy app in 
-[`test/dummy`](https://github.com/xdissent/git_wit/tree/master/test/dummy) for 
-a more advanced example of `authorized_keys` management.
+Something not working? `rake git_wit:ssh:debug`
 
 
 ## Git hooks and configs and umasks and everything

data/app/controllers/git_wit/git_controller.rb

@@ -11,38 +11,50 @@ module GitWit
 
     def service
       # Shell out to git-http-backend.
-      out, err, status = Open3.capture3 shell_env, GitWit.git_http_backend_path, 
-        stdin_data: request.raw_post, binmode: true
+      self.status, self.headers, self.response_body = run_shell
+    end
 
-      # Bail if the backend failed.
+    private
+    def run_shell
+      out, err, status = Open3.capture3 shell_env, shell_command, shell_opts
       raise GitError, err unless status.success?
+      parse_cgi_response out 
+    end
 
-      # Split headers and body from response.
-      headers, body = out.split("\r\n\r\n", 2)
-      
-      # Convert CGI headers to HTTP headers.
-      headers = Hash[headers.split("\r\n").map { |l| l.split(/\s*\:\s*/, 2) }]
+    def parse_cgi_response(cgi_response)
+      cgi_headers, body = cgi_response.split("\r\n\r\n", 2)
+      headers = parse_cgi_headers(cgi_headers)
+      [parse_cgi_status(headers), headers, body]
+    end
 
-      # Set status from header if given, otherwise it's a 200.
-      self.status = headers.delete("Status").to_i if headers.key? "Status"
+    def parse_cgi_headers(cgi_headers)
+      Hash[cgi_headers.split("\r\n").map { |l| l.split(/\s*\:\s*/, 2) }]
+    end
 
-      # Set response body if given, otherwise empty string.
-      self.response_body = body.presence || ""
+    def parse_cgi_status(cgi_headers)
+      cgi_headers.key?("Status") ? cgi_headers.delete("Status").to_i : 200
     end
 
-    private
     def shell_env
       request.headers.dup.extract!(*ENV_KEEPERS).merge(http_env).merge(git_env)
     end
 
+    def shell_command
+      [GitWit.git_path, "http-backend"].join " "
+    end
+
+    def shell_opts
+      {stdin_data: request.raw_post, binmode: true}
+    end
+
     def git_env
       {
         GIT_HTTP_EXPORT_ALL: "uknoit",
         GIT_PROJECT_ROOT: GitWit.repositories_path,
         PATH_INFO: "/#{params[:repository]}/#{params[:refs] || params[:service]}",
         REMOTE_USER: (user_attr(:username) || @username),
-        GIT_COMMITTER_NAME: user_attr(:committer_name),
-        GIT_COMMITTER_EMAIL: user_attr(:committer_email)
+        GIT_COMMITTER_NAME: user_attr(:name),
+        GIT_COMMITTER_EMAIL: user_attr(:email)
       }.reject { |_, v| v.nil? }.stringify_keys
     end
 
@@ -63,7 +75,7 @@ module GitWit
       end
 
       # Request credentials again if provided and no user was authenticated.
-      if @user.nil? && request.authorization.present?
+      if !@user.present? && request.authorization.present?
         request_http_basic_authentication_if_allowed
       end
     end
@@ -79,7 +91,7 @@ module GitWit
 
     def authorize_write
       # Never allow anonymous write operations.
-      return request_http_basic_authentication_if_allowed if @user.nil?
+      return request_http_basic_authentication_if_allowed unless @user.present?
 
       # Disallow write operations over insecure protocol per configuration.
       raise ForbiddenError if !GitWit.insecure_write && !request.ssl?
@@ -89,9 +101,9 @@ module GitWit
     end
 
     def authorize_read
-      return if GitWit.authorize_read(@user, params[:repository])
-      return request_http_basic_authentication_if_allowed if @user.nil?
-      raise UnauthorizedError
+      return true if GitWit.authorize_read(@user, params[:repository])
+      raise UnauthorizedError if @user.present?
+      request_http_basic_authentication_if_allowed
     end
 
     # TODO: Sure about this?
@@ -105,12 +117,14 @@ module GitWit
     end
 
     def user_attr(sym)
-      try_user GitWit.config.send("#{sym}_attribute")
+      try_user GitWit.send("#{sym}_attribute")
     end
 
     def try_user(sym_or_proc)
-      return @user.try(sym_or_proc) if sym_or_proc.is_a? Symbol
-      sym_or_proc.call(@user) if sym_or_proc.respond_to? :call
+      return sym_or_proc.call(@user) if sym_or_proc.respond_to? :call
+      if sym_or_proc.is_a?(Symbol) && @user.respond_to?(sym_or_proc)
+        @user.try(sym_or_proc)
+      end
     end
   end
 end

data/bin/git_wit

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require "git_wit/cli"
+GitWit::Cli.start ARGV

data/config/routes.rb

@@ -1,5 +1,5 @@
 GitWit::Engine.routes.draw do
-  get ":repository/*refs" => "git#service", repository: /[\-\/\w\.]+\.git/
-  post ":repository/:service" => "git#service", repository: /[\-\/\w\.]+\.git/, 
+  get ":repository/*refs", to: "git#service", repository: /[\-\/\w\.]+\.git/
+  post ":repository/:service", to: "git#service", repository: /[\-\/\w\.]+\.git/, 
     service: /git-[\w\-]+/
 end

data/lib/generators/git_wit/install/install_generator.rb

@@ -1,15 +1,46 @@
-class GitWit::InstallGenerator < Rails::Generators::Base
-  source_root File.expand_path('../../templates', __FILE__)
+module GitWit
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('../templates', __FILE__)
 
-  def copy_initializer
-    template "git_wit.rb", "config/initializers/git_wit.rb"
-  end
+    argument :attributes, type: :array, default: [], banner: "config[:value] config[:value]"
 
-  def show_readme
-    readme "README" if behavior == :invoke
-  end
+    def initialize(args, *options)
+      super
+      parse_attributes! if respond_to?(:attributes)
+    end
+
+    def copy_initializer
+      template "git_wit.rb", "config/initializers/git_wit.rb"
+    end
+
+    def show_readme
+      readme "README" if behavior == :invoke
+    end
+
+    def mount_route
+      route 'mount GitWit::Engine => "/"'
+    end
+
+    protected
+    def parse_attributes!
+      attrs = (attributes || [])
+      self.attributes = Hash[attrs.map { |attr| parse_attribute(attr) }.compact]
+    end
+
+    def parse_attribute(attr)
+      k, v = attr.split(":", 2)
+      v ||= true
+      v = false if v == "false"
+      [k.to_sym, v] if k.present?
+    end
 
-  def mount_route
-    route 'mount GitWit::Engine => "/"'
+    def maybe_config(name, default)
+      given = attributes.key?(name)
+      value = given ? attributes[name] : default
+      value = %("#{value}") if value.is_a? String
+      value = ":#{value}" if value.is_a? Symbol
+      pre = given ? "" : "# "
+      "#{pre}config.#{name} = #{value}"
+    end
   end
-end
+end