psc 0.0.1

data/.gitignore

@@ -0,0 +1,13 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+reports
+
+int-psc/downloads
+int-psc/bin/*
+int-psc/deploy-base
+int-psc/baseline.properties
+int-psc/datasource.properties
+
+.yardoc

data/.rvmrc

@@ -0,0 +1,2 @@
+rvm_gemset_create_on_use_flag=1; rvm use @psc-rb
+

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+--markup markdown
+--hide-void-return
+--files CHANGELOG.md,int-psc/README-int-psc.md

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+0.0.1
+=====
+
+- Initial version

data/Gemfile

@@ -0,0 +1,20 @@
+source "http://rubygems.org/"
+
+gemspec
+
+group :development do
+  # For yard's markdown support
+  platforms :jruby do
+    gem 'maruku'
+  end
+
+  platforms :ruby_18, :ruby_19 do
+    gem 'rdiscount'
+  end
+
+  # To prevent jruby problems in development
+  platforms :jruby do
+    gem 'jruby-openssl' # when using webmock
+    gem 'ffi-ncurses'   # when loading highline
+  end
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Rhett Sutphin
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,163 @@
+(Beware: [Readme-driven development in
+progress](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html). This
+is documentation for expected features, not for the current state of
+the library.)
+
+# psc.rb
+
+`psc.rb` is a ruby client for [Patient Study Calendar][psc]'s RESTful
+HTTP API. It provides assistance with authentication to PSC's API and
+with executing common tasks. It also provides a lower-level interface
+(`Psc::Connection`) to allow for making HTTP requests against the
+configured PSC's API directly.
+
+By design, the client provides a very thin abstraction over the API
+itself. Please be familiar with the API (whose documentation is
+available in your PSC instance at `api/v1/docs` or [on the demo
+site][demo-docs]) before using this library.
+
+[psc]: https://code.bioinformatics.northwestern.edu/issues/wiki/psc
+[demo-docs]: https://demos.nubic.northwestern.edu/psc/api/v1/docs
+
+## Overview
+
+    require 'psc'
+    require 'pp'
+
+    psc = Psc::Client.new(
+      'https://demos.nubic.northwestern.edu/psc',
+      :authenticator => { :basic => ['superuser', 'superuser'] }
+    )
+
+    pp psc.studies
+
+(This code will run if you have the psc gem installed; try it and see.)
+
+## Installing
+
+`psc.rb` is available as a rubygem:
+
+    $ gem install psc
+
+## Authentication
+
+PSC supports two forms of authentication for API calls: HTTP Basic
+(i.e., username & password) and psc_token. (Which forms are supported
+in your PSC instance will depend on its authentication system
+configuration.)
+
+A particular client instance will only use one authentication
+mechanism. There are three options.
+
+### HTTP Basic
+
+PSC Client allows you to specify a username and password to use for
+all requests. Include the `:authenticator` key like so:
+
+    :authenticator => { :basic => %w(alice password) }
+
+    => Authorization: Basic YWxpY2U6cGFzc3dvcmQ=
+
+### Static token
+
+Alternatively, you can provide a token to use in all requests:
+
+    :authenticator => { :token => 'The raven flies at midnight' }
+
+    => Authorization: psc_token The raven flies at midnight
+
+### Dynamic token
+
+Finally, you can provide a callable object which will be invoked for
+each request and whose return value will be used for the PSC token:
+
+    :authenticator => { :token => lambda { cas_client.get_proxy_ticket } }
+
+    => Authorization: psc_token PT-133-236H522
+
+The callable will be called with no arguments.
+
+## High-level interface
+
+{Psc::Client} provides a high-level interface to some of PSC's API
+capabilities.
+
+## Low-level interface
+
+`psc.rb` is based on [Faraday][], a modular ruby HTTP
+client. {Psc::Connection} is a Faraday connection configured
+for access to a particular PSC instance. You can create a
+`Psc::Connection` directly:
+
+    conn = Psc::Connection.new(
+      'https://demos.nubic.northwestern.edu/psc',
+      :authenticator => { :basic => %w(superuser superuser) })
+
+Or you can get an instance from the {Psc::Client} high-level
+interface:
+
+    client = Psc::Client.new(
+      'https://demos.nubic.northwestern.edu/psc',
+      :authenticator => { :basic => %w(superuser superuser) })
+    conn = client.connection
+
+The connection is set up to automatically parse JSON reponses into
+appropriate ruby primitives and XML responses into [Nokogiri][]
+documents.
+
+    studies_json = conn.get('studies.json')
+    first_study_name =
+      studies_json.body['studies'].first['assigned_identifier']
+
+    sites_xml = conn.get('sites.xml')
+    first_site_name =
+      sites_xml.body.xpath('//psc:site', Psc.xml_namespace).first.attr('site-name')
+
+Similarly, for PUT and POST it will encode a `Hash` or
+`Array` entity as JSON and will assume that a `String` entity is XML.
+
+[Faraday]: https://github.com/technoweenie/faraday
+[Nokogiri]: http://nokogiri.org/
+
+### URLs
+
+PSC's API resources all start with `api/v1`. To help you DRY things
+up, `PSC::Connection` automatically adds this to the base URL on
+construction. You don't need to include it when constructing
+relative URLs.
+
+### Middleware
+
+Faraday connections are built up from middleware. `Psc::Connection`
+uses a combination of off-the-shelf and custom middleware classes. The
+custom classes are in the {Psc::Faraday} module.
+
+## Project info
+
+* [Source code][github]
+* [API Documentation][rubydoc]
+* [Bug reports and feature requests][issues]
+* [Continuous integration][ci]
+* Version policy: [semantic versioning][semver]
+
+[rubydoc]: http://rubydoc.info/gems/psc
+[issues]: https://github.com/NUBIC/psc.rb/issues
+[github]: https://github.com/NUBIC/psc.rb
+[ci]: https://ctms-ci.nubic.northwestern.edu/hudson/jobs/psc.rb
+[semver]: http://semver.org/
+
+### Running the tests
+
+`psc.rb` has an rspec suite for unit tests and a set of cucumber
+features for integration tests. Before you can run the cucumber
+features you will need to either
+
+ * Execute `rake int-psc:war` to download a copy of PSC to use
+ * Copy a PSC war into `int-psc/bin`
+
+### Patches
+
+Patches with tests are happily considered. Please use a [pull
+request][].
+
+[pull request]: http://help.github.com/pull-requests/

data/Rakefile

@@ -0,0 +1,69 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'ci/reporter/rake/rspec'
+require 'cucumber/rake/task'
+require 'yard'
+
+Dir[File.expand_path('../tasks/*.rake', __FILE__)].each { |f| load f }
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new('spec') do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+  t.verbose = true
+  t.rspec_opts = ['--format', 'html', '--out', 'reports/spec.html', '--format', 'p']
+end
+
+task :cucumber => 'cucumber:ok'
+
+namespace :cucumber do
+  Cucumber::Rake::Task.new(:ok, "Run features that should pass") do |t|
+    t.fork = true
+    t.profile = "default"
+  end
+
+  Cucumber::Rake::Task.new(:wip, "Run features that are being worked on") do |t|
+    t.fork = true
+    t.profile = "wip"
+  end
+
+  Cucumber::Rake::Task.new(
+    :wip_platform, "Run features that are flagged as failing on the current platform"
+  ) do |t|
+    t.fork = true
+    t.profile = "wip_platform"
+  end
+
+  desc "Run all features"
+  task :all => [:ok, :wip, :wip_platform]
+end
+
+task :yard => ['yard:auto']
+
+namespace :yard do
+  desc "Run a server which will rebuild documentation as the source changes"
+  task :auto do
+    system("bundle exec yard server --reload")
+  end
+
+  desc "Build API documentation with yard"
+  YARD::Rake::YardocTask.new("once") do |t|
+    t.options = ["--title", "psc.rb #{Psc::VERSION}"]
+  end
+end
+
+namespace :ci do
+  ENV["CI_REPORTS"] = "reports/spec-xml"
+
+  desc "Run specs for CI"
+  task :spec => ['ci:setup:rspec', 'rake:spec']
+
+  Cucumber::Rake::Task.new(:cucumber, 'Run features using the ci profile') do |t|
+    t.fork = true
+    t.profile = 'ci'
+  end
+
+  # currently bypassing ci_reporter due to https://github.com/nicksieger/ci_reporter/issues/5
+  task :build => %w(int-psc:war int-psc:clean_logs rake:spec cucumber)
+end

data/cucumber.yml

@@ -0,0 +1,13 @@
+<% platform =
+    if RUBY_PLATFORM == 'java'
+      'jruby'
+    elsif RUBY_VERSION =~ /^1.9/
+      '19'
+    else
+      '18'
+    end
+%>
+default: --strict --tags ~@wip --tags ~@no_<%= platform %> features
+wip: --tags @wip:3 --wip --tags ~@no_<%= platform %> features
+ci: --tags ~@wip --tags ~@badci --tags ~@no_<%= platform %> --format html --out reports/cucumber.html --format junit --out reports/cucumber-xml --format progress --strict features
+wip_platform: --tags @no_<%= platform %> --wip features

data/features/step_definitions/eval_steps.rb

@@ -0,0 +1,14 @@
+When /^I evaluate the following code:$/ do |string|
+  int_psc.wait_for
+  @captured_out = StringIO.new
+  begin
+    $stdout = @captured_out
+    eval(string)
+  ensure
+    $stdout = STDOUT
+  end
+end
+
+Then /^I should see this output:$/ do |string|
+  @captured_out.string.strip.should == string
+end

data/features/step_definitions/setup_steps.rb

@@ -0,0 +1,7 @@
+Given /^that PSC is deployed$/ do
+  int_psc.boot
+end
+
+Given /^I have a PSC::Client instance$/ do
+  init_client
+end

data/features/studies.feature

@@ -0,0 +1,21 @@
+Feature: List studies
+
+In order to understand what templates are available
+A developer should be able to use Psc::Client to list the studies in a PSC instance
+
+Background:
+  Given that PSC is deployed
+    And I have a PSC::Client instance
+
+Scenario: List studies
+   When I evaluate the following code:
+    """
+    s = client.studies
+    puts "Study count: #{s.size}"
+    puts "First study: #{s.first['assigned_identifier']}"
+    """
+   Then I should see this output:
+    """
+    Study count: 1
+    First study: ABC 1200
+    """

data/features/support/env.rb

@@ -0,0 +1,33 @@
+require 'bundler'
+Bundler.setup
+
+require 'rspec'
+
+$LOAD_PATH.unshift File.expand_path("../../../lib", __FILE__)
+
+require 'psc'
+
+module Psc::Cucumber
+  include ::RSpec::Matchers
+
+  class World
+    def int_psc
+      @int_psc ||= IntPsc.new
+    end
+
+    def init_client
+      @client = Psc::Client.new(
+        File.join(IntPsc.url, 'api/v1'),
+        :authenticator => { :basic => [ 'superuser' ] * 2 }
+      )
+    end
+
+    def client
+      @client
+    end
+  end
+end
+
+World do
+  Psc::Cucumber::World.new
+end

data/features/support/int_psc.rb

@@ -0,0 +1,165 @@
+# Utilities for starting and stopping a PSC instance for integration testing
+
+require 'childprocess'
+require 'open-uri'
+require 'timeout'
+require 'forwardable'
+require 'fileutils'
+
+class IntPsc
+  DEFAULT_CONFIGURATION_NAME='datasource'
+
+  extend Forwardable
+  include FileUtils
+
+  def self.path(*bits)
+    File.join(File.expand_path('../../..', __FILE__), 'int-psc', *bits)
+  end
+  def_delegator self, :path
+
+  def self.port
+    ENV['INT_PSC_PORT'] ||= '7209'
+  end
+  def_delegator self, :port
+
+  def self.url
+    "http://localhost:#{port}/"
+  end
+  def_delegator self, :url
+
+  def self.warfile
+    path('bin', 'psc.war')
+  end
+  def_delegator self, :warfile
+
+  def self.expanded_war_directory
+    path('deploy-base', 'webapps', 'ROOT')
+  end
+  def_delegator self, :expanded_war_directory
+
+  def self.run(configuration=DEFAULT_CONFIGURATION_NAME)
+    psc = self.new(configuration)
+    psc.boot
+    puts "Waiting for PSC's API to become available"
+    psc.wait_for
+    yield psc
+    psc.stop
+  end
+
+  attr_reader :configuration_name
+
+  def initialize(configuration=DEFAULT_CONFIGURATION_NAME)
+    @configuration_name = configuration
+  end
+
+  def boot
+    expand_if_necessary
+    create_hsql_psc_configuration
+
+    cmd = [
+      'java',
+      ENV['JAVA_OPTS'],
+      "-Dpsc.config.datasource=#{configuration_name}",
+      "-Dpsc.config.path=#{path}",
+      '-Dpsc.logging.debug=true',
+      "-Dcatalina.base=#{path 'deploy-base'}",
+
+      '-jar',
+      # jetty-runner
+      path('jetty', 'jetty-runner-7.4.0.v20110414.jar'),
+      "--port", port,
+      expanded_war_directory
+    ].compact
+
+    @running_psc = ChildProcess.build(*cmd)
+    @running_psc.duplex = true
+
+    @output_capture = rolled_log('jetty.out')
+    @running_psc.io.stdout = @output_capture
+    @running_psc.io.stderr = @output_capture
+
+    at_exit { self.stop }
+    @running_psc.start
+    @running_psc.io.stdin.close # to turn off ShellTUI for the OSGi layer
+  end
+
+  def stop
+    if @running_psc && @running_psc.alive?
+      @running_psc.stop
+      @output_capture.close
+    end
+  end
+
+  def wait_for
+    Timeout.timeout(90) do
+      while true
+        begin
+          open(File.join(self.url, '/api/v1/docs')) { |f| f.read }
+          break
+        rescue RuntimeError
+          sleep(1)
+        rescue
+          sleep(1)
+        end
+      end
+    end
+  end
+
+  def create_hsql_psc_configuration
+    File.open(path("#{configuration_name}.properties"), 'w') do |f|
+      f.puts [
+        "datasource.url=jdbc:hsqldb:file:#{path('hsqldb', configuration_name)};shutdown=true",
+        'datasource.username=sa',
+        'datasource.password=',
+        'datasource.driver=org.hsqldb.jdbcDriver'
+      ].join("\n")
+    end
+  end
+
+  def apply_state_and_mark_readonly
+    client = Faraday.new(File.join(url, '/api/v1')) do |builder|
+      builder.adapter :net_http
+    end
+    client.basic_auth('superuser', 'superuser')
+    Psc::State.from_file(path('state/int-psc-state.xml')).apply(client)
+
+    File.open(path('hsqldb', "#{configuration_name}.properties"), 'a') do |f|
+      f.puts 'hsqldb.files_readonly=true'
+    end
+  end
+
+  private
+
+  def expand_if_necessary
+    dirtime = File.directory?(expanded_war_directory) ?
+      File.mtime(expanded_war_directory) :
+      Time.at(0)
+    wartime = File.mtime(warfile)
+    if wartime > dirtime
+      rm_rf expanded_war_directory
+      mkdir_p expanded_war_directory
+      cd expanded_war_directory do
+        system("jar xf '#{warfile}'")
+      end
+    end
+  end
+
+  def rolled_log(name)
+    log = path('deploy-base', 'logs', name)
+    mkdir_p File.dirname(log)
+    if File.exist?(log)
+      now_s = date_str_from_time(Time.new)
+      existing_s = date_str_from_time(File.mtime(log))
+      if now_s != existing_s
+        rolled_log_name = log.sub(/\.([^\.]+)$/, ".#{existing_s}.\\1")
+        mv log, rolled_log_name
+        system("gzip -N '#{rolled_log_name}'")
+      end
+    end
+    File.open(log, 'a')
+  end
+
+  def date_str_from_time(t)
+    t.iso8601.split('T').first
+  end
+end