bcdatabase 1.0.6 → 1.1.0

data/CHANGELOG.markdown

@@ -1,55 +1,74 @@
+Bcdatabase history
+==================
+
+1.1.0
+-----
+
+- Introduce "transforms" -- a way to attach behavior to modify entries
+  on load. See {Bcdatabase.load} for details.
+- Add `:datamapper` built-in transform to support sharing one set of
+  entries between ActiveRecord and DataMapper. (#10)
+- Rework command-line interface for better testability. It's now
+  compatible with MRI 1.9. (#11, #7)
+- Provide a better message when working with encrypted passwords and
+  the keyfile is not readable. (#1)
+- Improve `bcdatabase encrypt` so that it will work with a wider
+  variety of input passwords and YAML files. The remaining limitations
+  are documented in its online help. (#12)
+- Interpret empty stanzas as entries made up entirely of defaults. (#13)
+
 1.0.6
-=====
+-----
 - Use `ENV['RAILS_ENV']` instead of the unreliable `RAILS_ENV` constant.
 
 1.0.5
-=====
+-----
 - Loosen highline dependency so that bcdatabase can be used in buildr buildfiles.
 
 1.0.4
-=====
+-----
 - Fix command line utilities that were broken in 1.0.3 due to
   inadequate test coverage.  (GH-4)
 
 1.0.3
-=====
+-----
 - Support ActiveSupport 3.  ActiveSupport 2 continues to work.
 
 1.0.2
-=====
+-----
 - Tighten up gemspec gem deps.  Bcdatabase does not currently work
   with ActiveSupport 3.
 
 1.0.1
-=====
+-----
 - Update some old syntax for ruby 1.9 compatibility (David Yip)
 
 1.0.0
-=====
+-----
 - Split out from NUBIC internal `bcdatabase` project.
   (Changelog entries below reflect the relevant changes & version numbers from that project.)
 
 0.4.1
-=====
+-----
 - Fix `bcdatabase encrypt` so that it doesn't re-encrypt already encrypted
   epassword entries.
 
 0.4.0
-=====
+-----
 - Use the YAML entry name as the "database" value if no other value is
   provided.  This is to DRY up PostgreSQL configurations where the username
   (already defaulted) and the database name are the same.
 
 0.2.0
-=====
+-----
 - Change default encrypted secret password location
 
 0.1.0
-=====
+-----
 - Support encrypted passwords
 - Command-line utility (also called bcdatabase) for creating encrypted passwords
 - Gem distribution
 
 0.0.0
-=====
+-----
 Original release.

data/README.markdown

@@ -1,7 +1,14 @@
-bcdatabase
+Bcdatabase
 ==========
 
-*bcdatabase* is a library and utility which provides database configuration parameter management for Ruby on Rails applications.  It provides a simple mechanism for separating database configuration attributes from application source code so that there's no temptation to check passwords into the version control system.  And it centralizes the parameters for a single server so that they can be easily shared among multiple applications and easily updated by a single administrator.
+*Bcdatabase* is a library and utility which provides database
+configuration parameter management for Ruby on Rails applications.  It
+provides a simple mechanism for separating database configuration
+attributes from application source code so that there's no temptation
+to check passwords into the version control system.  And it
+centralizes the parameters for a single server so that they can be
+easily shared among multiple applications and easily updated by a
+single administrator.
 
 ## Installing bcdatabase
 
@@ -9,7 +16,7 @@ bcdatabase
 
 ## Using bcdatabase to configure the database for a Rails application
 
-A bog-standard rails application's `config/database.yml` file looks like this:
+A bog-standard Rails application's `config/database.yml` file looks like this:
 
     development:
       adapter: oracle_enhanced
@@ -29,7 +36,10 @@ A bog-standard rails application's `config/database.yml` file looks like this:
       username: cfg_animal
       password: very-secret
 
-Rails allows this file to contain [ERB][].  `bcdatabase` uses ERB to replace an entire configuration block.  If you wanted to replace, say, just the production block in this example, you would transform it like so:
+Rails allows this file to contain [ERB][].  `bcdatabase` uses ERB to
+replace an entire configuration block.  If you wanted to replace, say,
+just the production block in this example, you would transform it like
+so:
 
     <%
       require 'bcdatabase'
@@ -50,7 +60,9 @@ Rails allows this file to contain [ERB][].  `bcdatabase` uses ERB to replace an
 
     <%= bcdb.production :prod, :cfg_animal %>
 
-This means "create a YAML block for the *production* environment from the configuration entry named *cfg_animal* in /etc/nubic/db/*prod*.yml."  The method called can be anything:
+This means "create a YAML block for the *production* environment from
+the configuration entry named *cfg_animal* in
+/etc/nubic/db/*prod*.yml."  The method called can be anything:
 
     <%= bcdb.development :local, :cfg_animal %>
     <%= bcdb.staging 'stage', 'cfg_animal' %>
@@ -60,21 +72,33 @@ This means "create a YAML block for the *production* environment from the config
 
 ## Directly accessing configuration parameters from bcdatabase
 
-More rarely, you might need to access the actual configuration hash, instead of the YAMLized version.  You can access it by invoking `Bcdatabase.load` as shown earlier, then using the bracket operator to specify the configuration you want:
+More rarely, you might need to access the actual configuration hash,
+instead of the YAMLized version.  You can access it by invoking
+`Bcdatabase.load` as shown earlier, then using the bracket operator to
+specify the configuration you want:
 
     bcdb[:local, :cfg_animal]
 
-The resulting hash is suitable for passing to `ActiveRecord::Base.establish_connection`, for instance.
+The resulting hash is suitable for passing to
+`ActiveRecord::Base.establish_connection`, for instance.
 
 ## Central configuration files
 
-The database configuration properties for all the applications on a server are stored in one or more files under `/etc/nubic/db` (by default; see "File locations" below).  Each one is a standard YAML file, similar to rails' `database.yml` but with a few enhancements:
+The database configuration properties for all the applications on a
+server are stored in one or more files under `/etc/nubic/db` (by
+default; see "File locations" below).  Each one is a standard YAML
+file, similar to Rails' `database.yml` but with a few enhancements:
 
-* Each file can have a defaults entry which provides attributes which are shared across all configurations in the file
-* Each entry defaults its "username" attribute to the name of the entry (useful for Oracle)
-* Each entry defaults its "database" attribute to the name of the entry (useful for PostgreSQL)
+* Each file can have a defaults entry which provides attributes which
+  are shared across all configurations in the file
+* Each entry defaults its "username" attribute to the name of the
+  entry (useful for Oracle)
+* Each entry defaults its "database" attribute to the name of the
+  entry (useful for PostgreSQL)
 
-Since each file can define a set of default properties which are shared by all the contained configurations, it makes sense to group databases which have some shared configuration elements.
+Since each file can define a set of default properties which are
+shared by all the contained configurations, it makes sense to group
+databases which have some shared configuration elements.
 
 ### Example
 
@@ -96,7 +120,7 @@ You have defined two configuration entries.  `:stage, :cfg_animal`:
     password: secret
     database: //mondo/stage
 
-and `:bcstage, :personnel`:
+and `:stage, :personnel`:
 
     adapter:  oracle_enhanced
     username: pers
@@ -105,33 +129,104 @@ and `:bcstage, :personnel`:
 
 ## Obscuring passwords
 
-bcdatabase supports storing encrypted passwords instead of the plaintext ones shown in the previous example.  Encrypted passwords are defined with the key `epassword` instead of `password`.  The library will decrypt the `epassword` value and expose it to the calling code (usually rails) unencrypted under the `password` key.  The `bcdatabase` command line utility handles encrypting passwords; see the next section.
+Bcdatabase supports storing encrypted passwords instead of the
+plaintext ones shown in the previous example.  Encrypted passwords are
+defined with the key `epassword` instead of `password`.  The library
+will decrypt the `epassword` value and expose it to the calling code
+(usually Rails) unencrypted under the `password` key.  The
+`bcdatabase` command line utility handles encrypting passwords; see
+the next section.
 
-While the passwords are technically encrypted, the master key must be stored on the same machine so that they can be decrypted on demand.  That means this feature only obscures passwords &mdash; it will not deter a determined attacker.
+While the passwords are technically encrypted, the master key must be
+stored on the same machine so that they can be decrypted on demand.
+That means this feature only obscures passwords &mdash; it will not
+deter a determined attacker.
 
 ## `bcdatabase` command line utility
 
-The gem includes a command line utility (also called `bcdatabase`) which assists with creating `epassword` entries.  It has online help; after installing the gem, try `bcdatabase help` to read it:
+The gem includes a command line utility (also called `bcdatabase`)
+which assists with creating `epassword` entries.  It has online help;
+after installing the gem, try `bcdatabase help` to read it:
 
     $ bcdatabase help
-    usage: bcdatabase <command> [args]
-    Command-line utility for bcdatabase 1.0.0
-      encrypt  Encrypts all the password entries in a bcdatabase YAML file
-        epass  Generate epasswords from individual database passwords
-      gen-key  Generate a key for bcdatabase to use
-         help  List commands or display help for one
+    Tasks:
+      bcdatabase encrypt [INPUT [OUTPUT]]  # Encrypt every password in a bcdatabase YAML file
+      bcdatabase epass [-]                 # Generate epasswords from database passwords
+      bcdatabase gen-key [-]               # Generate the bcdatabase shared key
+      bcdatabase help [TASK]               # Describe available tasks or one specific task
 
 ## File locations
 
-`/etc/nubic/db` is the default place the library will look for the central configuration files.  It may be overridden with the environment variable `BCDATABASE_PATH`.  For instance, if you wanted to keep these files in your home directory on your development machine &mdash; perhaps so that editing them doesn't require elevated privileges &mdash; you could add this to `~/.bashrc`:
+`/etc/nubic/db` is the default place the library will look for the
+central configuration files.  It may be overridden with the
+environment variable `BCDATABASE_PATH`.  For instance, if you wanted
+to keep these files in your home directory on your development machine
+&mdash; perhaps so that editing them doesn't require elevated
+privileges &mdash; you could add this to `~/.bashrc`:
 
     export BCDATABASE_PATH=${HOME}/nubic/db
 
-Similarly, the file containing the encryption password has a sensible default location, but that location can be overridden by setting `BCDATABASE_PASS`.
+Similarly, the file containing the encryption password has a sensible
+default location, but that location can be overridden by setting
+`BCDATABASE_PASS`.
+
+## DataMapper
+
+Bcdatabase was originally designed for use with ActiveRecord in Rails
+applications. Since [DataMapper][dm]'s programmatic configuration mechanism
+(`Datamapper.setup`) accepts hashes which are very similar to
+ActiveRecord configuration hashes, Bcdatabase can easily be used with
+DataMapper as well. Example:
+
+    bcdb = Bcdatabase.load(:transforms => [:datamapper]))
+    DataMapper.setup(:default, bcdb[:stage, :personnel])
+
+The `:datamapper` transform passed to `Bcdatabase.load` in this
+example permits sharing of one set of Bcdatabase configurations
+between ActiveRecord and DataMapper-based apps. Specifically, for
+those cases where the ActiveRecord adapter and the DataMapper adapter
+have different names, it allows you to specify a separate
+`datamapper_adapter` in your Bcdatabase configuration. For example,
+say you had these contents in `stage.yml`:
+
+    defaults:
+      adapter: postgresql
+      datamapper_adapter: postgres
+    personnel:
+      password: foo
+
+When loaded without the `:datamapper` transform, the effective
+database configuration hash for `:stage, :personnel` would be
+
+    adapter: postgresql
+    datamapper_adapter: postgres # ignored by AR
+    database: personnel
+    username: personnel
+
+With the `:datamapper` transform, the result would be instead:
+
+    adapter: postgres
+    database: personnel
+    username: personnel
+
+And so your DM and AR apps can live side-by-side and neither needs to
+embed its own database credentials.
+
+[dm]: http://datamapper.org/
+
+## Platforms
+
+Bcdatabase works on MRI 1.8.7 and MRI 1.9.2. It will also work on
+JRuby (tested on 1.6+), provided that `jruby-openssl` is also
+installed. It is [continuously tested][ci] on all three of these
+platforms.
+
+[ci]: https://public-ci.nubic.northwestern.edu/job/bcdatabase/
 
 ## Credits
 
-`bcdatabase` was developed at and for the [Northwestern University Biomedical Informatics Center][NUBIC].
+`bcdatabase` was developed at and for the [Northwestern University
+Biomedical Informatics Center][NUBIC].
 
 [NUBIC]: http://www.nucats.northwestern.edu/centers/nubic/index.html
 

data/bcdatabase.gemspec

@@ -0,0 +1,30 @@
+lib = File.expand_path('../lib/', __FILE__)
+$:.unshift lib unless $:.include?(lib)
+
+require 'bcdatabase/version'
+
+Gem::Specification.new do |s|
+  s.name = 'bcdatabase'
+  s.version = Bcdatabase::VERSION
+  s.summary = %Q{Server-central database configuration for rails and other ruby apps}
+  s.description = %Q{bcdatabase is a tool for storing passwords and other configuration information outside of your application source tree.}
+  s.email = "rhett@detailedbalance.net"
+  s.homepage = "http://github.com/NUBIC/bcdatabase"
+  s.authors = ["Rhett Sutphin"]
+
+  s.require_paths = ["lib"]
+
+  s.executables = ['bcdatabase']
+  s.files = Dir.glob("{CHANGELOG.markdown,LICENSE,README.markdown,bcdatabase.gemspec,{bin,lib}/**/*}")
+
+  s.add_dependency "activesupport", ">= 2.0"
+  s.add_dependency "highline", "~> 1.5"
+  s.add_dependency "i18n"
+  s.add_dependency 'thor', '~> 0.14.6'
+
+  s.add_development_dependency 'bundler', '~> 1.0.15'
+  s.add_development_dependency 'rake', '~> 0.9.2'
+  s.add_development_dependency 'rspec','~> 2.6'
+  s.add_development_dependency "ci_reporter", "~> 1.6"
+  s.add_development_dependency 'yard', '~> 0.7.2'
+end

data/bin/bcdatabase

@@ -1,26 +1,20 @@
-#!/usr/bin/env ruby -W
+#!/usr/bin/env ruby
 
-require 'rubygems'
-require 'bcdatabase/commands'
-
-module Bcdatabase::Commands
-  UTILITY_NAME = File.basename(__FILE__)
+# Allow this executable to be run directly from the source as well as
+# from an installed gem.
+begin
+  lib = File.expand_path('../../lib', __FILE__)
+  unless $LOAD_PATH.include?(lib)
+    $LOAD_PATH << lib
+    require 'rubygems'
+  end
 end
 
-###### MAIN
-
-command = ARGV.shift
-unless command
-  $stderr.puts "Please specify a command."
-  $stderr.puts Bcdatabase::Commands.help
-  exit(1)
-end
+require 'bcdatabase'
 
-klass = Bcdatabase::Commands[command]
-unless klass
-  $stderr.puts "Unknown command #{command}."
-  $stderr.puts Bcdatabase::Commands.help
-  exit(2)
+begin
+  Bcdatabase::CLI.start
+rescue Interrupt => e
+  $stderr.puts "Interrupted"
+  exit 1
 end
-
-exit(klass.new(ARGV).main)

data/lib/bcdatabase/cli.rb

@@ -0,0 +1,81 @@
+require 'bcdatabase'
+require 'thor'
+
+module Bcdatabase
+  class CLI < Thor
+    desc "encrypt [INPUT [OUTPUT]]",
+      "Encrypt every password in a bcdatabase YAML file"
+    long_desc <<-DESC
+      This command finds all the keys named 'password' in the input
+      YAML and substitutes appropriate 'epassword' keys.
+
+      If inputfile is specified, the source will be that file. If not,
+      the source will be standard in.
+
+      If inputfile and outputfile are specified, the new file will be
+      written to the output file. Otherwise the output will go to
+      standard out. Input and output may be the same file.
+
+      You can't read from standard in and write to a file directly;
+      use shell file redirection if you need to do that.
+
+      N.b.: this command works with a subset of legal YAML
+      files. Specifically, it will only work if the 'password' key and
+      value are entirely on the same line. If for some reason you
+      can't arrange for your input files to meet this restriction, you
+      can use the epass subcommand to encrypt one password at a time.
+    DESC
+    def encrypt(inputfile=nil, outputfile=nil)
+      Commands::Encrypt.new(inputfile, outputfile).run
+    end
+
+    desc 'epass [-]', 'Generate epasswords from database passwords'
+    long_desc <<-DESC
+      With no arguments, interactively prompts for passwords and
+      prints the corresponding epassword entry.
+
+      If the last argument is -, reads a newline-separated list of
+      passwords from standard in and prints the corresponding
+      epasswords to standard out.
+    DESC
+    def epass(arg=nil)
+      Commands::Epass.new(arg == '-').run
+    end
+
+    desc 'gen-key [-]', 'Generate the bcdatabase shared key'
+    long_desc <<-DESC
+      Generates the key that is used to obscure epasswords. By
+      default, the key will be generated in
+      #{Bcdatabase.pass_file}.  If the last argument to this command
+      is -, the key will be generated to standard out instead.
+
+      CAUTION: writing to #{Bcdatabase.pass_file} may overwrite an
+      existing bcdatabase key.  If that happens, you will need to
+      reencrypt all the epasswords on this machine.
+    DESC
+    def gen_key(arg=nil)
+      Commands::GenKey.new(arg == '-').run
+    end
+
+    no_tasks do
+      # Add uniform exception handling
+      [:encrypt, :epass, :gen_key].each do |original|
+        alias_method "#{original}_without_rescue".to_sym, original
+
+        class_eval <<-RUBY
+          def #{original}(*args)
+            #{original}_without_rescue(*args)
+          rescue SystemCallError => e
+            shell.say("\#{e.class}: \#{e}", :RED)
+            exit(8)
+          rescue Bcdatabase::Error => e
+            shell.say(e.message, :RED)
+            exit(4)
+          rescue Commands::ForcedExit => e
+            exit(e.code)
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/bcdatabase/commands/encrypt.rb

@@ -0,0 +1,47 @@
+require 'bcdatabase/commands'
+
+module Bcdatabase::Commands
+  class Encrypt
+    def initialize(inputfile=nil, outputfile=nil)
+      @input = (Pathname.new(inputfile) if inputfile)
+      @output = (Pathname.new(outputfile) if outputfile)
+    end
+
+    def run
+      begin
+        # try to preserve the order by replacing everything using regexes
+        contents = inio.read
+        contents.gsub!(/\bpassword:.*?$/) { |line|
+          "epassword: #{Bcdatabase.encrypt(YAML.load(line)['password'])}"
+        }
+        outio.write(contents)
+      ensure
+        @inio.close if @close_in && @inio
+        @outio.close if @close_out && @outio
+      end
+    end
+
+    private
+
+    def inio
+      @inio ||=
+        if @input
+          @close_in = true
+          @input.open('r')
+        else
+          $stdin
+        end
+    end
+
+    def outio
+      @outio ||=
+        if @output
+          @output.dirname.mkpath
+          @close_out = true
+          @output.open('w')
+        else
+          $stdout
+        end
+    end
+  end
+end

data/lib/bcdatabase/commands/epass.rb

@@ -0,0 +1,40 @@
+require 'bcdatabase/commands'
+
+require 'highline'
+
+module Bcdatabase::Commands
+  class Epass
+    def initialize(streaming, opts={})
+      @streaming = streaming
+      @echo = opts[:echo].nil? ? false : opts[:echo]
+      @hl = HighLine.new($stdin, $stderr)
+    end
+
+    def run
+      @streaming ? streamed : interactive
+    end
+
+    protected
+
+    def streamed
+      $stdin.readlines.each do |line|
+        puts Bcdatabase.encrypt(line.chomp)
+      end
+    end
+
+    def interactive
+      loop do
+        pass = @hl.ask("Password (^C to end): ") do |q|
+          # this is configurable because having it false hangs the
+          # unit tests.
+          q.echo = @echo
+        end
+        puts "  epassword: #{Bcdatabase.encrypt(pass)}"
+      end
+    rescue Interrupt
+      $stderr.puts "Quit"
+    rescue EOFError
+      $stderr.puts "Quit"
+    end
+  end
+end

data/lib/bcdatabase/commands/gen_key.rb

@@ -0,0 +1,48 @@
+require 'bcdatabase/commands'
+require 'highline'
+require 'pathname'
+
+module Bcdatabase::Commands
+  class GenKey
+    def initialize(streaming)
+      @streaming = streaming
+      @hl = HighLine.new($stdin, $stderr)
+    end
+
+    def run
+      begin
+        key = random_key(128)
+        outio.write key
+      ensure
+        @outio.close if @close_out && @outio
+      end
+    end
+
+    private
+
+    def random_key(length)
+      (1..length).collect { rand(255) }.pack('C*')
+    end
+
+    def outio
+      @outio ||=
+        if @streaming
+          $stdout
+        else
+          open_key_file
+        end
+    end
+
+    def open_key_file
+      filename = Pathname.new(Bcdatabase.pass_file)
+      if filename.exist?
+        unless @hl.agree("This operation will overwrite the existing pass file.\n  Are you sure you want to do that? (y/n) ")
+          raise ForcedExit.new(1)
+        end
+      end
+      @close_out = true
+      filename.dirname.mkpath
+      filename.open('w')
+    end
+  end
+end

data/lib/bcdatabase/commands.rb

@@ -1,241 +1,15 @@
-require 'rubygems'
-require 'fileutils'
-require 'highline'
-require 'active_support'
-require 'active_support/core_ext/string/inflections'
 require 'bcdatabase'
 
-HL = HighLine.new
-
 module Bcdatabase::Commands
-  class Base
-    protected
-
-    def self.usage(use)
-      "usage: #{UTILITY_NAME} #{use}"
-    end
-
-    def self.help_message(use)
-      msg = [ "#{command_name}: #{summary}", usage(use), "" ]
-      yield msg if block_given?
-      msg.join("\n")
-    end
-  end
-
-  class Epass < Base
-    def initialize(argv)
-      @streaming = argv[-1] == '-'
-    end
-
-    def self.summary
-      "Generate epasswords from individual database passwords"
-    end
-
-    def self.help
-      help_message("epass [-]") do |msg|
-        msg << "With no arguments, interactively prompts for passwords and"
-        msg << "  prints the corresponding epassword entry."
-        msg << ""
-        msg << "If the last argument is -, reads a newline-separated list"
-        msg << "  of passwords from standard in and prints the corresponding "
-        msg << "  epasswords to standard out."
-      end
-    end
-
-    def main
-      @streaming ? streamed : interactive
-    end
-
-    private
-
-    def streamed
-      $stdin.readlines.each do |line|
-        puts Bcdatabase.encrypt(line.chomp)
-      end
-      0
-    end
-
-    def interactive
-      begin
-        loop do
-          pass = HL.ask("Password (^C to end): ") do |q|
-            q.echo = false
-          end
-          puts "  epassword: #{Bcdatabase.encrypt(pass)}"
-        end
-      rescue Interrupt
-        puts "\nQuit"
-      end
-      0
-    end
-  end
-
-  class Encrypt < Base
-    def initialize(argv)
-      @input = argv.shift
-      @output = argv.shift
-    end
-
-    def self.summary
-      "Encrypts all the password entries in a bcdatabase YAML file"
-    end
-
-    def self.help
-      help_message("encrypt [inputfile [outputfile]]") do |msg|
-        msg << "Specifically, this command finds all the keys named 'password'"
-        msg << "  in the input YAML and substitutes appropriate 'epassword'"
-        msg << "  keys."
-        msg << ""
-        msg << "If inputfile is specified, the source will be that file."
-        msg << "  If not, the source will be standard in."
-        msg << ""
-        msg << "If inputfile and outputfile are specified, the new file"
-        msg << "  will be written to the output file.  Otherwise the output"
-        msg << "  will go to standard out.  Input and output may be the same"
-        msg << "  file."
-        msg << ""
-        msg << "You can't read from standard in and write to a file directly; "
-        msg << "  use shell file redirection if you need to do that."
-      end
-    end
-
-    def main
-      inio =
-        if @input
-          open(@input, "r")
-        else
-          $stdin
-        end
-      # try to preserve the order by replacing everything using regexes
-      contents = inio.read
-      contents.gsub!(/\bpassword:(\s*)(\S+)\s*?$/) { "epassword:#{$1}#{Bcdatabase.encrypt($2)}" }
-      outio =
-        if @output
-          open(@output, "w")
-        else
-          $stdout
-        end
-      outio.write(contents)
-      outio.close
-      0
-    end
-  end
-
-  class Help < Base
-    def initialize(argv)
-      @cmd = argv.shift
-    end
-
-    def self.summary
-      "List commands or display help for one; e.g. #{UTILITY_NAME} help epass"
-    end
-
-    def self.help
-      help_message "help [command name]"
-    end
-
-    def main
-      if @cmd
-        klass = Bcdatabase::Commands[@cmd]
-        if klass
-          msg = klass.respond_to?(:help) ? klass.help : klass.summary
-          $stderr.puts msg
-        else
-          $stderr.puts "Unknown command #{@cmd}"
-          return 1
-        end
-      else
-        $stderr.puts Bcdatabase::Commands.help
-      end
-      0
-    end
-  end
-
-  class GenKey < Base
-    def initialize(argv)
-      @stream = argv[-1] == '-'
-    end
-
-    def self.summary
-      "Generate a key for bcdatabase to use"
-    end
+  autoload :Encrypt, 'bcdatabase/commands/encrypt'
+  autoload :Epass,   'bcdatabase/commands/epass'
+  autoload :GenKey,  'bcdatabase/commands/gen_key'
 
-    def self.help
-      help_message("gen-key [-]") do |msg|
-        msg << "By default, the key will be generated in "
-        msg << "  #{Bcdatabase.pass_file}.  If the last argument to this"
-        msg << "  command is -, the key will be generated to standard out"
-        msg << "  instead."
-        msg << ""
-        msg << "CAUTION: writing to #{Bcdatabase.pass_file} may overwrite"
-        msg << "  an existing bcdatabase key.  If that happens, you will"
-        msg << "  need to reencrypt all the epasswords on this machine."
-      end
-    end
-
-    def main
-      key = random_key(128)
-      outio =
-        if @stream
-          $stdout
-        else
-          file = Bcdatabase.pass_file
-          if File.exist?(file)
-            sure = HL.ask("This operation will overwrite the existing pass file.\n  Are you sure you want to do that? ", %w{yes no}) do |q|
-              q.case = :down
-            end
-            unless sure == 'yes'
-              exit(0)
-            end
-          end
-          open(file, "w")
-        end
-      outio.write key
-      outio.close
-      0
-    end
-
-    private
-
-    def random_key(length)
-      k = ""
-      # This is probably not going to work in ruby 1.9
-      until k.size == length; k << rand(126 - 32) + 32; end
-      k
-    end
-  end
+  class ForcedExit < StandardError
+    attr_reader :code
 
-  class << self
-    def help
-      all_help = commands.collect { |c| [c.command_name, c.summary] }.sort_by { |p| p[0] }
-      max_name_length = all_help.collect { |a| a[0].size }.max
-      msg = Base.usage "<command> [args]\n"
-      msg << "Utility for bcdatabase #{Bcdatabase::VERSION}\n"
-      msg << "Commands:\n"
-      msg << all_help.collect { |name, help| " %#{max_name_length + 1}s  %s" % [name, help] }.join("\n")
+    def initialize(code)
+      @code = code
     end
-
-    # Lists all the commands
-    def commands
-      constants.reject { |cs| cs == "Base" }.collect { |cs| const_get(cs) }.select { |c| c.kind_of? Class }
-    end
-
-    # Locates the command class for a user-entered command name.
-    # Returns nil if the name is invalid.
-    def command(command_name)
-      begin
-        klassname = command_name.gsub('-', '_').camelize
-        Bcdatabase::Commands.const_get "#{klassname}"
-      rescue NameError
-        nil
-      end
-    end
-    alias :[] :command
-  end
-end
-
-class Class
-  def command_name
-    name.gsub(Bcdatabase::Commands.name + "::", '').underscore.gsub("_", '-')
   end
 end

data/lib/bcdatabase/version.rb

@@ -1,3 +1,3 @@
 module Bcdatabase
-  VERSION = '1.0.6'
+  VERSION = '1.1.0'
 end

data/lib/bcdatabase.rb

@@ -2,9 +2,14 @@ require 'yaml'
 require 'openssl'
 require 'digest/sha2'
 require 'base64'
+require 'pathname'
+
+# Requiring just extract_options doesn't work on AS 2.3.
+require 'active_support/core_ext/array'
 
 module Bcdatabase
   autoload :VERSION,  'bcdatabase/version'
+  autoload :CLI,      'bcdatabase/cli'
   autoload :Commands, 'bcdatabase/commands'
 
   DEFAULT_BASE_PATH = File.join('/', 'etc', 'nubic', 'db')
@@ -12,22 +17,51 @@ module Bcdatabase
   CIPHER = 'aes-256-ecb'
 
   class << self
-    def load(path=nil)
-      path ||= base_path
+    ##
+    # The main entry point for Bcdatabase.
+    #
+    # @overload load(options={})
+    #   (See other alternative for option definitions.)
+    #   @return [DatabaseConfigurations] a new instance using the
+    #     default path.
+    # @overload load(path=nil, options={})
+    #   @param [String,nil] path the directory to load from. If nil,
+    #     will use the value in the environment variable
+    #     `BCDATABASE_PATH`. If that's nil, too, it will use the
+    #     default path.
+    #   @param [Hash,nil] options additional options affecting the
+    #     load behavior.
+    #   @option options :transforms [Array<Symbol, #call>] ([]) Custom
+    #     transforms. This can either be a symbol naming a
+    #     {DatabaseConfigurations.BUILT_IN_TRANSFORMS built-in
+    #     transform} or a callable which is the transform itself. A
+    #     transform is a function that takes three arguments (the
+    #     entry itself, the entry name, and the group name) and
+    #     returns a new copy, modified as desired. It may also return
+    #     nil to indicate that it doesn't wish to make any changes.
+    #   @return [DatabaseConfigurations] a new instance reflecting
+    #     the selected path.
+    def load(*args)
+      options = args.extract_options!
+      path ||= (args.first || base_path)
       files = Dir.glob(File.join(path, "*.yml")) + Dir.glob(File.join(path, "*.yaml"))
-      DatabaseConfigurations.new(files)
+      DatabaseConfigurations.new(files, options[:transforms] || [])
     end
 
+    ##
+    # @private exposed for collaboration
     def encrypt(s)
       Base64.encode64(encipher(:encrypt, s)).strip
     end
 
+    ##
+    # @private exposed for collaboration
     def decrypt(s)
       encipher(:decrypt, Base64.decode64(s))
     end
 
     def pass_file
-      ENV["BCDATABASE_PASS"] || DEFAULT_PASS_FILE
+      Pathname.new(ENV["BCDATABASE_PASS"] || DEFAULT_PASS_FILE)
     end
 
     private
@@ -43,15 +77,30 @@ module Bcdatabase
     end
 
     def pass
-      return @pass if instance_variable_defined? :@pass
-
-      contents = open(pass_file).read.chomp
-      # This code may not work correctly on Ruby 1.9
-      if contents.size == 32
-        @pass = contents
-      else
-        @pass = Digest::SHA256.digest(contents)
+      @passes ||= { }
+      @passes[pass_file] ||=
+        begin
+          contents = read_pass_file
+          # This code may not work correctly on Ruby 1.9
+          if contents.size == 32
+            contents
+          else
+            Digest::SHA256.digest(contents)
+          end
+        end
+    end
+
+    def read_pass_file
+      unless pass_file.readable?
+        msg = [
+          "Bcdatabase keyfile #{pass_file} is not readable. Possible solutions:",
+          "* Use bcdatabase gen-key to generate a key",
+          "* Change the path by setting BCDATABASE_PASS in the environment",
+          "* Check the permissions on #{pass_file}"
+        ].compact.join("\n")
+        raise Bcdatabase::Error, msg
       end
+      pass_file.read
     end
 
     def base_path
@@ -59,8 +108,36 @@ module Bcdatabase
     end
   end
 
+  ##
+  # The set of groups and entries returned by one call to {Bcdatabase.load}.
   class DatabaseConfigurations
-    def initialize(files)
+    BUILT_IN_TRANSFORMS = {
+      :key_defaults => lambda { |entry, name, group|
+        { 'username' => name, 'database' => name }.merge(entry)
+      },
+      :decrypt => lambda { |entry, name, group|
+        entry.merge({ 'password' => Bcdatabase.decrypt(entry['epassword']) }) if entry['epassword']
+      },
+      :datamapper => lambda { |entry, name, group|
+        entry.merge('adapter' => entry['datamapper_adapter']) if entry['datamapper_adapter']
+      }
+    }
+
+    ##
+    # Creates a configuration from a set of YAML files.
+    #
+    # General use of the library should not use this method, but
+    # instead should use {Bcdatabase.load}.
+    def initialize(files, transforms=[])
+      @transforms = ([:key_defaults, :decrypt] + transforms).collect do |t|
+        case t
+        when Symbol
+          BUILT_IN_TRANSFORMS[t] or fail "No built-in transform named #{t.inspect}"
+        else
+          fail 'Transforms must by callable' unless t.respond_to?(:call)
+          t
+        end
+      end
       @files = files
       @map = { }
       files.each do |filename|
@@ -69,10 +146,18 @@ module Bcdatabase
       end
     end
 
+    ##
+    # @return [Hash] the entry for the given group and name after all
+    #   transformation is complete.
     def [](groupname, dbname)
       create_entry(groupname.to_s, dbname.to_s)
     end
 
+    ##
+    # This method implements the Rails database.yml integration
+    # described in full in the {file:README.markdown}.
+    #
+    # @return [String] a YAMLized view of a configuration entry.
     def method_missing(name, *args)
       groupname = (args[0] or raise "Database configuration group not specified for #{name}")
       dbname = (args[1] or raise "Database entry name not specified for #{name}")
@@ -94,16 +179,16 @@ module Bcdatabase
 
     def create_entry(groupname, dbname)
       group = @map[groupname] or raise Error.new("No database configuration group named #{groupname.inspect} found.  (Found #{@map.keys.inspect}.)")
-      db = group[dbname] or raise Error.new("No database entry for #{dbname.inspect} in #{groupname}")
-      merged = { 'username' => dbname, 'database' => dbname } \
-        .merge(group['defaults'] || {}) \
-        .merge(group['default'] || {}) \
-        .merge(db)
-      # include the decrypted password if an encrypted one was provided
-      if merged['epassword']
-        merged['password'] = Bcdatabase.decrypt(merged['epassword'])
+      unless group.has_key?(dbname)
+        raise Error.new("No database entry for #{dbname.inspect} in #{groupname}.")
+      end
+      db = group[dbname] || {}
+      base = (group['defaults'] || {}).
+        merge(group['default'] || {}).
+        merge(db)
+      @transforms.inject(base) do |result, transform|
+        transform.call(result, dbname, groupname) || result
       end
-      merged
     end
 
     def unseparated_yaml(arg)
@@ -111,5 +196,5 @@ module Bcdatabase
     end
   end
 
-  class Error < Exception; end
+  class Error < StandardError; end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: bcdatabase
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 19
   prerelease: false
   segments: 
   - 1
+  - 1
   - 0
-  - 6
-  version: 1.0.6
+  version: 1.1.0
 platform: ruby
 authors: 
 - Rhett Sutphin
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-28 00:00:00 -05:00
+date: 2011-08-30 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -63,24 +63,72 @@ dependencies:
   type: :runtime
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: thor
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 11
+        hash: 43
+        segments: 
+        - 0
+        - 14
+        - 6
+        version: 0.14.6
+  type: :runtime
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
         segments: 
         - 1
+        - 0
+        - 15
+        version: 1.0.15
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 63
+        segments: 
+        - 0
+        - 9
         - 2
-        version: "1.2"
+        version: 0.9.2
   type: :development
-  version_requirements: *id004
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 2
+        - 6
+        version: "2.6"
+  type: :development
+  version_requirements: *id007
 - !ruby/object:Gem::Dependency 
   name: ci_reporter
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -91,8 +139,24 @@ dependencies:
         - 6
         version: "1.6"
   type: :development
-  version_requirements: *id005
-description: bcdatabase is a tool for storing passwords and other database configuration information outside of your application source tree.
+  version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id009 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 0
+        - 7
+        - 2
+        version: 0.7.2
+  type: :development
+  version_requirements: *id009
+description: bcdatabase is a tool for storing passwords and other configuration information outside of your application source tree.
 email: rhett@detailedbalance.net
 executables: 
 - bcdatabase
@@ -104,12 +168,17 @@ files:
 - CHANGELOG.markdown
 - LICENSE
 - README.markdown
+- bcdatabase.gemspec
 - bin/bcdatabase
+- lib/bcdatabase/cli.rb
+- lib/bcdatabase/commands/encrypt.rb
+- lib/bcdatabase/commands/epass.rb
+- lib/bcdatabase/commands/gen_key.rb
 - lib/bcdatabase/commands.rb
 - lib/bcdatabase/version.rb
 - lib/bcdatabase.rb
 has_rdoc: true
-homepage: http://github.com/rsutphin/bcdatabase
+homepage: http://github.com/NUBIC/bcdatabase
 licenses: []
 
 post_install_message: