ood_core 0.0.1

data/lib/ood_core/clusters.rb

@@ -0,0 +1,114 @@
+require "yaml"
+
+module OodCore
+  # An enumerable that contains a list of {Cluster} objects
+  class Clusters
+    include Enumerable
+
+    # The format version of the configuration file
+    CONFIG_VERSION = ['v2', 'v1']
+
+    class << self
+      # Parse a configuration file or a set of configuration files in a
+      # directory
+      # @param path [#to_s] configuration file or directory path
+      # @raise [ConfigurationNotFound] if path does not exist
+      # @return [Clusters] the clusters parsed from config
+      def load_file(path)
+        config = Pathname.new(path.to_s).expand_path
+
+        clusters = []
+        if config.file?
+          CONFIG_VERSION.any? do |version|
+            YAML.safe_load(config.read).fetch(version, {}).each do |k, v|
+              clusters << Cluster.new(send("parse_#{version}", id: k, cluster: v))
+            end
+            !clusters.empty?
+          end
+        elsif config.directory?
+          Pathname.glob(config.join("*.yml")).each do |p|
+            CONFIG_VERSION.any? do |version|
+              if cluster = YAML.safe_load(p.read).fetch(version, nil)
+                clusters << Cluster.new(send("parse_#{version}", id: p.basename(".yml").to_s, cluster: cluster))
+                true
+              else
+                false
+              end
+            end
+          end
+        else
+          raise ConfigurationNotFound, "configuration file '#{config}' does not exist"
+        end
+
+        new clusters
+      end
+
+      private
+        # Parse a list of clusters from a 'v1' config
+        # NB: Makes minimum assumptions about config
+        def parse_v1(id:, cluster:)
+          c = {
+            id: id,
+            metadata: {},
+            login: {},
+            job: {},
+            acls: [],
+            custom: {}
+          }
+
+          c[:metadata][:title]   = cluster["title"] if cluster.key?("title")
+          c[:metadata][:url]     = cluster["url"]   if cluster.key?("url")
+          c[:metadata][:private] = true             if cluster["cluster"]["data"]["hpc_cluster"] == false
+
+          if l = cluster["cluster"]["data"]["servers"]["login"]
+            c[:login][:host] = l["data"]["host"]
+          end
+
+          if rm = cluster["cluster"]["data"]["servers"]["resource_mgr"]
+            c[:job][:adapter] = "torque"
+            c[:job][:host]    = rm["data"]["host"]
+            c[:job][:lib]     = rm["data"]["lib"]
+            c[:job][:bin]     = rm["data"]["bin"]
+            c[:job][:acls]    = []
+          end
+
+          if v = cluster["validators"]
+            if vc = v["cluster"]
+              c[:acls] = vc.map do |h|
+                {
+                  adapter: "group",
+                  groups: h["data"]["groups"],
+                  type: h["data"]["allow"] ? "whitelist" : "blacklist"
+                }
+              end
+            end
+          end
+
+          c
+        end
+
+        # Parse a list of clusters from a 'v2' config
+        def parse_v2(id:, cluster:)
+          cluster.merge(id: id)
+        end
+    end
+
+    # @param clusters [Array<Cluster>] list of cluster objects
+    def initialize(clusters = [])
+      @clusters = clusters
+    end
+
+    # Find cluster in list using the id of the cluster
+    # @param id [Object] id of cluster object
+    # @return [Cluster, nil] cluster object if found
+    def [](id)
+      @clusters.detect { |cluster| cluster == id }
+    end
+
+    # For a block {|cluster| ...}
+    # @yield [cluster] Gives the next cluster object in the list
+    def each(&block)
+      @clusters.each(&block)
+    end
+  end
+end

data/lib/ood_core/errors.rb

@@ -0,0 +1,19 @@
+module OodCore
+  # Generic {OodCore} exception class
+  class Error < StandardError; end
+
+  # Raised when cannot find configuration file specified
+  class ConfigurationNotFound < Error; end
+
+  # Raised when adapter not specified in configuration
+  class AdapterNotSpecified < Error; end
+
+  # Raised when cannot find adapter specified in configuration
+  class AdapterNotFound < Error; end
+
+  # Raised when job adapter encounters an error with resource manager
+  class JobAdapterError < Error; end
+
+  # Raised when a job state is set to an invalid option
+  class UnknownStateAttribute < Error; end
+end

data/lib/ood_core/job/adapter.rb

@@ -0,0 +1,89 @@
+module OodCore
+  module Job
+    # A class that handles the communication with a resource manager for
+    # submitting/statusing/holding/deleting jobs
+    # @abstract
+    class Adapter
+      # Submit a job with the attributes defined in the job template instance
+      # @abstract Subclass is expected to implement {#submit}
+      # @raise [NotImplementedError] if subclass did not define {#submit}
+      # @example Submit job template to cluster
+      #   solver_id = job_adapter.submit(solver_script)
+      #   #=> "1234.server"
+      # @example Submit job that depends on previous job
+      #   post_id = job_adapter.submit(
+      #     post_script,
+      #     afterok: solver_id
+      #   )
+      #   #=> "1235.server"
+      # @param script [Script] script object that describes the
+      #   script and attributes for the submitted job
+      # @param after [#to_s, Array<#to_s>] this job may be scheduled for execution
+      #   at any point after dependent jobs have started execution
+      # @param afterok [#to_s, Array<#to_s>] this job may be scheduled for
+      #   execution only after dependent jobs have terminated with no errors
+      # @param afternotok [#to_s, Array<#to_s>] this job may be scheduled for
+      #   execution only after dependent jobs have terminated with errors
+      # @param afterany [#to_s, Array<#to_s>] this job may be scheduled for
+      #   execution after dependent jobs have terminated
+      # @return [String] the job id returned after successfully submitting a job
+      def submit(script, after: [], afterok: [], afternotok: [], afterany: [])
+        raise NotImplementedError, "subclass did not define #submit"
+      end
+
+      # Retrieve info for all jobs from the resource manager
+      # @abstract Subclass is expected to implement {#info_all}
+      # @raise [NotImplementedError] if subclass did not define {#info_all}
+      # @return [Array<Info>] information describing submitted jobs
+      def info_all
+        raise NotImplementedError, "subclass did not define #info_all"
+      end
+
+      # Retrieve job info from the resource manager
+      # @abstract Subclass is expected to implement {#info}
+      # @raise [NotImplementedError] if subclass did not define {#info}
+      # @param id [#to_s] the id of the job
+      # @return [Info] information describing submitted job
+      def info(id)
+        raise NotImplementedError, "subclass did not define #info"
+      end
+
+      # Retrieve job status from resource manager
+      # @note Optimized slightly over retrieving complete job information from server
+      # @abstract Subclass is expected to implement {#status}
+      # @raise [NotImplementedError] if subclass did not define {#status}
+      # @param id [#to_s] the id of the job
+      # @return [Status] status of job
+      def status(id)
+        raise NotImplementedError, "subclass did not define #status"
+      end
+
+      # Put the submitted job on hold
+      # @abstract Subclass is expected to implement {#hold}
+      # @raise [NotImplementedError] if subclass did not define {#hold}
+      # @param id [#to_s] the id of the job
+      # @return [void]
+      def hold(id)
+        raise NotImplementedError, "subclass did not define #hold"
+      end
+
+      # Release the job that is on hold
+      # @abstract Subclass is expected to implement {#release}
+      # @raise [NotImplementedError] if subclass did not define {#release}
+      # @param id [#to_s] the id of the job
+      # @return [void]
+      def release(id)
+        raise NotImplementedError, "subclass did not define #release"
+      end
+
+      # Delete the submitted job
+      # @abstract Subclass is expected to implement {#delete}
+      # @raise [NotImplementedError] if subclass did not define {#delete}
+      # @param id [#to_s] the id of the job
+      # @return [void]
+      def delete(id)
+        raise NotImplementedError, "subclass did not define #delete"
+      end
+    end
+  end
+end

data/lib/ood_core/job/adapters/lsf.rb

@@ -0,0 +1,193 @@
+require "ood_core/refinements/hash_extensions"
+
+module OodCore
+  module Job
+    class Factory
+      using Refinements::HashExtensions
+
+      # Build the Lsf adapter from a configuration
+      # @param config [#to_h] the configuration for job adapter
+      # @option config [#to_s] :bindir ('') Path to lsf client bin dir
+      # @option config [#to_s] :libdir ('') Path to lsf client lib dir
+      # @option config [#to_s] :envdir ('') Path to lsf client conf dir
+      # @option config [#to_s] :serverdir ('') Path to lsf client etc dir
+      def self.build_lsf(config)
+        batch = Adapters::Lsf::Batch.new(config.to_h.symbolize_keys)
+        Adapters::Lsf.new(batch: batch)
+      end
+    end
+
+    module Adapters
+      class Lsf < Adapter
+        # @api private
+        attr_reader :batch, :helper
+
+        require "ood_core/job/adapters/lsf/batch"
+        require "ood_core/job/adapters/lsf/helper"
+
+        STATE_MAP = {
+          'RUN' => :running,
+          'PEND' => :queued,
+          'DONE' => :completed,
+          'EXIT' => :completed,
+
+          'PSUSP' => :queued_held, # supsended before job started, resumable via bresume
+          'USUSP' => :suspended, # suspended after job started, resumable via bresume
+          'SSUSP' => :suspended,
+
+          'WAIT' => :queued, # FIXME: not sure what else to do here
+          'ZOMBI' => :undetermined,
+          'UNKWN' => :undetermined
+        }
+
+        # @param opts [#to_h] the options defining this adapter
+        # @option opts [Batch] :batch The Lsf batch object
+        #
+        # @api private
+        # @see Factory.build_lsf
+        def initialize(batch:)
+          @batch = batch
+          @helper = Lsf::Helper.new
+        end
+
+        # Submit a job with the attributes defined in the job template instance
+        # @param script [Script] script object that describes the script and
+        #   attributes for the submitted job
+        # @param after [#to_s, Array<#to_s>] this job may be scheduled for
+        #   execution at any point after dependent jobs have started execution
+        # @param afterok [#to_s, Array<#to_s>] this job may be scheduled for
+        #   execution only after dependent jobs have terminated with no errors
+        # @param afternotok [#to_s, Array<#to_s>] this job may be scheduled for
+        #   execution only after dependent jobs have terminated with errors
+        # @param afterany [#to_s, Array<#to_s>] this job may be scheduled for
+        #   execution after dependent jobs have terminated
+        # @raise [JobAdapterError] if something goes wrong submitting a job
+        # @return [String] the job id returned after successfully submitting a
+        #   job
+        # @see Adapter#submit
+        def submit(script, after: [], afterok: [], afternotok: [], afterany: [])
+          # ensure dependencies are array of ids
+          after      = Array(after).map(&:to_s)
+          afterok    = Array(afterok).map(&:to_s)
+          afternotok = Array(afternotok).map(&:to_s)
+          afterany   = Array(afterany).map(&:to_s)
+
+          args = []
+          args += ["-P", script.accounting_id] unless script.accounting_id.nil?
+          args += ["-cwd", script.workdir.to_s] unless script.workdir.nil?
+          args += ["-J", script.job_name] unless script.job_name.nil?
+
+          # TODO: dependencies
+
+          env = {
+            #TODO:
+            #LSB_HOSTS?
+            #LSB_MCPU_HOSTS?
+            #SNDJOBS_TO?
+            #
+          }
+
+          # Submit job
+          batch.submit_string(script.content, args: args, env: env)
+
+        rescue Batch::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Retrieve job info from the resource manager
+        # @param id [#to_s] the id of the job
+        # @raise [JobAdapterError] if something goes wrong getting job info
+        # @return [Info] information describing submitted job
+        # @see Adapter#info
+        def info(id)
+          # TODO: handle job arrays
+          job = batch.get_job(id: id)
+          job ? info_for_batch_hash(job) : nil
+        rescue Batch::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Retrieve info for all jobs from the resource manager
+        # @raise [JobAdapterError] if something goes wrong getting job info
+        # @return [Array<Info>] information describing submitted jobs
+        # @see Adapter#info_all
+        def info_all
+          batch.get_jobs.map { |v| info_for_batch_hash(v) }
+        rescue Batch::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Retrieve job status from resource manager
+        # @param id [#to_s] the id of the job
+        # @raise [JobAdapterError] if something goes wrong getting job status
+        # @return [Status] status of job
+        # @see Adapter#status
+        def status(id)
+          job = batch.get_job(id: id)
+          state = job ? get_state(job[:status]) : :completed
+          Status.new(state: state)
+        rescue Batch::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Put the submitted job on hold
+        # @param id [#to_s] the id of the job
+        # @raise [JobAdapterError] if something goes wrong holding a job
+        # @return [void]
+        # @see Adapter#hold
+        def hold(id)
+          batch.hold_job(id.to_s)
+        rescue Batch::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Release the job that is on hold
+        # @param id [#to_s] the id of the job
+        # @raise [JobAdapterError] if something goes wrong releasing a job
+        # @return [void]
+        # @see Adapter#release
+        def release(id)
+          batch.release_job(id.to_s)
+        rescue Batch::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Delete the submitted job
+        # @param id [#to_s] the id of the job
+        # @raise [JobAdapterError] if something goes wrong deleting a job
+        # @return [void]
+        # @see Adapter#delete
+        def delete(id)
+          batch.delete_job(id.to_s)
+        rescue Batch::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        private
+          # Determine state from LSF state code
+          def get_state(st)
+            STATE_MAP.fetch(st, :undetermined)
+          end
+
+          def info_for_batch_hash(v)
+            Info.new(
+              id: v[:id],
+              status: get_state(v[:status]),
+              allocated_nodes: [],
+              submit_host: v[:from_host],
+              job_name: v[:name],
+              job_owner: v[:user],
+              accounting_id: v[:project],
+              procs: nil,
+              queue_name: v[:queue],
+              wallclock_time: nil,
+              cpu_time: nil,
+              submission_time: helper.parse_past_time(v[:submit_time], ignore_errors: true),
+              dispatch_time: helper.parse_past_time(v[:start_time], ignore_errors: true),
+              native: v
+            )
+          end
+      end
+    end
+  end
+end

data/lib/ood_core/job/adapters/lsf/batch.rb

@@ -0,0 +1,160 @@
+# Object used for simplified communication with a LSF batch server
+#
+# @api private
+class OodCore::Job::Adapters::Lsf::Batch
+  attr_reader :bindir, :libdir, :envdir, :serverdir
+
+  # The root exception class that all LSF-specific exceptions inherit
+  # from
+  class Error < StandardError; end
+
+  # @param bin [#to_s] path to LSF installation binaries
+  def initialize(bindir: "", envdir: "", libdir: "", serverdir: "", **_)
+    @bindir = Pathname.new(bindir.to_s)
+
+    @envdir = Pathname.new(envdir.to_s)
+    @libdir = Pathname.new(libdir.to_s)
+    @serverdir = Pathname.new(serverdir.to_s)
+  end
+
+  def default_env
+    {
+      "LSF_BINDIR" => bindir.to_s,
+      "LSF_LIBDIR" => libdir.to_s,
+      "LSF_ENVDIR" => envdir.to_s,
+      "LSF_SERVERDIR" => serverdir.to_s
+    }.reject {|k,v| v.nil? || v.empty? }
+  end
+
+  # Get a list of hashes detailing each of the jobs on the batch server
+  # @raise [Error] if `bjobs` command exited unsuccessfully
+  # @return [Array<Hash>] list of details for jobs
+  def get_jobs
+    #TODO: split into get_all_jobs, get_my_jobs
+    args = bjobs_default_args
+    parse_bjobs_output(call("bjobs", *args))
+  end
+
+  # Get hash detailing the specified job
+  # @param id [#to_s] the id of the job to check
+  # @raise [Error] if `bjobs` command exited unsuccessfully
+  # @return [Hash] details of specified job
+  def get_job(id:)
+    args = bjobs_default_args
+    args << id.to_s
+    parse_bjobs_output(call("bjobs", *args)).first
+  end
+
+  def bjobs_default_args
+    %w( -u all -a -w -W )
+  end
+
+    # status fields available from bjobs
+    def fields
+      %i(id user status queue from_host exec_host name submit_time
+          project cpu_used mem swap pids start_time finish_time)
+    end
+
+  # helper method
+  def parse_bjobs_output(response)
+    return [] if response =~ /No job found/ || response.nil?
+
+    lines = response.split("\n")
+    validate_bjobs_output_columns(lines.first.split)
+
+    lines.drop(1).map{ |job|
+      values = split_bjobs_output_line(job)
+
+      # make a hash of { field: "value", etc. }
+      Hash[fields.zip(values)].each_with_object({}) { |(k,v),o|
+        # if the value == "-", replace it with nil
+        o[k] = (v == "-" ? nil : v)
+      }
+    }
+  end
+
+
+  # Put a specified job on hold
+  # @example Put job "1234" on hold
+  #   my_batch.hold_job("1234")
+  # @param id [#to_s] the id of the job
+  # @raise [Error] if `bstop` command exited unsuccessfully
+  # @return [void]
+  def hold_job(id)
+    call("bstop", id.to_s)
+  end
+
+  # Release a specified job that is on hold
+  # @example Release job "1234" from on hold
+  #   my_batch.release_job("1234")
+  # @param id [#to_s] the id of the job
+  # @raise [Error] if `bresume` command exited unsuccessfully
+  # @return [void]
+  def release_job(id)
+    call("bresume", id.to_s)
+  end
+
+  # Delete a specified job from batch server
+  # @example Delete job "1234"
+  #   my_batch.delete_job("1234")
+  # @param id [#to_s] the id of the job
+  # @raise [Error] if `bkill` command exited unsuccessfully
+  # @return [void]
+  def delete_job(id)
+    call("bkill", id.to_s)
+  end
+
+  # Submit a script expanded as a string to the batch server
+  # @param str [#to_s] script as a string
+  # @param args [Array<#to_s>] arguments passed to `sbatch` command
+  # @param env [Hash{#to_s => #to_s}] environment variables set
+  # @raise [Error] if `bsub` command exited unsuccessfully
+  # @return [String] the id of the job that was created
+  def submit_string(str, args: [], env: {})
+    args = args.map(&:to_s)
+    parse_bsub_output(call("bsub", *args, env: env, stdin: str.to_s))
+  end
+
+  # helper method
+  def parse_bsub_output(response)
+    if response =~ /Job <(.*)> /
+      $1
+    else
+      nil
+    end
+  end
+
+  private
+    # Call a forked Lsf command for a given cluster
+    def call(cmd, *args, env: {}, stdin: "")
+      cmd = bindir.join(cmd.to_s).to_s
+      #TODO: args = ["-m", cluster] + args.map(&:to_s)
+      env = default_env.merge(env.to_h)
+      o, e, s = Open3.capture3(env, cmd, *(args.map(&:to_s)), stdin_data: stdin.to_s)
+      s.success? ? o : raise(Error, e)
+    end
+
+    # split a line of output from bjobs into field values
+    def split_bjobs_output_line(line)
+      values = line.strip.split
+
+      if(values.count > 15)
+        # FIXME: hack assumes 15 fields & only job name may have spaces
+        # collapse >15 fields into 15, assumes 7th field is JOB_NAME
+        values = values[0..5] + [values[6..-9].join(" ")] + values[-8..-1]
+      end
+
+      values
+    end
+
+    # verify the output from bjobs is parsable by this object
+    def validate_bjobs_output_columns(columns)
+      expected = %w(JOBID USER STAT QUEUE FROM_HOST EXEC_HOST JOB_NAME
+                    SUBMIT_TIME PROJ_NAME CPU_USED MEM SWAP PIDS START_TIME FINISH_TIME)
+      if columns != expected
+        raise Error, "bjobs output in different format than expected: " \
+          "#{columns.inspect} instead of #{expected.inspect}"
+      end
+    end
+
+end