p4_web_api_client 2014.2.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 199bda143441561260c895321ab9c1c57d42a4ef
+  data.tar.gz: 30f094cc9402abdbc2b60707b4f16f03db187c57
+SHA512:
+  metadata.gz: d91a36aad1d32dc268db168db220f0d5951cc3aabc28d53fe6b3ed6789c1c0ea30e9d07717bc458191df98870f9788dfa9d2b08e93b096ccc2335ee4e9bdc280
+  data.tar.gz: 3500061dd4dd4084729653a53ad1a4bc269dec65d2761727d110691f6673e5860a256d0e3ad80a5da736d4e83025949c340ba5ae156e5eb1c379374edd3dc1cf

data/lib/p4_web_api_client/client/branches.rb

@@ -0,0 +1,41 @@
+require 'open-uri'
+require 'p4_web_api_client/models/branch'
+
+module P4WebApiClient
+  class Client
+    # Array of Branch objects stored in the system. Not all fields will be
+    # filled out (e.g., view).
+    def branches
+      arr = execute_method_no_body(:get, '/branches')
+      arr.map { |a| Models::Branch.new(a) }
+    end
+
+    # Returns the branch instance indicated by the branch name (or model)
+    def branch(branch)
+      branch = branch.branch if branch.is_a?(Models::Branch)
+      obj = execute_method_with_body(:get, "branches/#{URI.encode(branch)}")
+      Models::Branch.new(obj)
+    end
+
+    # Creates a new branch in the system.
+    def create_branch(branch)
+      branch = Models::Branch.new(branch) unless branch.is_a?(Models::Branch)
+      execute_method_with_body(:post, '/branches', branch.to_internal_hash)
+      true
+    end
+
+    # Updates the branch specification.
+    def update_branch(branch)
+      execute_method_with_body(:put, "/branches/#{URI.encode(branch.branch)}",
+                               branch.to_internal_hash)
+      true
+    end
+
+    # Deletes the branch specification in the system.
+    def delete_branch(branch)
+      branch = branch.branch if branch.is_a?(Models::Branch)
+      execute_method_no_body(:delete, "branches/#{URI.encode(branch)}")
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client/changes.rb

@@ -0,0 +1,17 @@
+require 'p4_web_api_client/models/change'
+
+module P4WebApiClient
+  class Client
+    # List changelists in the system
+    #
+    # options:
+    # - :max: cap the number of results
+    # - :status: :pending, :submitted, or :shelved (see Change)
+    # - :user: The perforce login to check out
+    # - :files: Depot path pattern to restrict changes to
+    def changes(options = nil)
+      arr = execute_method_no_body(:get, '/changes', options)
+      arr.map { |obj| Models::Change.new(obj) }
+    end
+  end
+end

data/lib/p4_web_api_client/client/clients.rb

@@ -0,0 +1,40 @@
+require 'p4_web_api_client/models/client'
+
+module P4WebApiClient
+  class Client
+    # Array of Client objects stored in the system. Not all fields will be
+    # filled out (e.g.,  view).
+    def clients
+      arr = execute_method_no_body(:get, '/clients')
+      arr.map { |a| Models::Client.new(a) }
+    end
+
+    # Returns the client instance indicated by the client name or model
+    def client(client)
+      client = client.client if client.is_a?(Models::Client)
+      obj = execute_method_no_body(:get, "/clients/#{URI.encode(client)}")
+      Models::Client.new(obj)
+    end
+
+    # Creates a new client in the system.
+    def create_client(client)
+      client = Models::Client.new(client) unless client.is_a?(Models::Client)
+      execute_method_with_body(:post, '/clients', client.to_internal_hash)
+      true
+    end
+
+    # Updates the client specification.
+    def update_client(client)
+      execute_method_with_body(:put, "/clients/#{URI.encode(client.client)}",
+                               client.to_internal_hash)
+      true
+    end
+
+    # Deletes the client specification in the system.
+    def delete_client(client)
+      client = client.client if client.is_a?(Models::Client)
+      execute_method_no_body(:delete, "/clients/#{URI.encode(client)}")
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client/depots.rb

@@ -0,0 +1,42 @@
+
+require 'open-uri'
+require 'p4_web_api_client/models/depot'
+
+module P4WebApiClient
+  class Client
+    # Array of Depot objects stored in the system. Not all fields will be
+    # filled out (e.g., view).
+    def depots
+      arr = execute_method_no_body(:get, '/depots')
+      arr.map { |a| Models::Depot.new(a) }
+    end
+
+    # Returns the depot instance indicated by the depot name (or depot object)
+    def depot(depot)
+      depot = depot.depot if depot.is_a?(Models::Depot)
+      obj = execute_method_no_body(:get, "/depots/#{URI.encode(depot)}")
+      Models::Depot.new(obj)
+    end
+
+    # Creates a new depot in the system.
+    def create_depot(depot)
+      depot = Models::Depot.new(depot) unless depot.is_a?(Models::Depot)
+      execute_method_with_body(:post, '/depots', depot.to_internal_hash)
+      true
+    end
+
+    # Updates the depot specification.
+    def update_depot(depot)
+      execute_method_with_body(:put, "/depots/#{URI.encode(depot.depot)}",
+                               depot.to_internal_hash)
+      true
+    end
+
+    # Deletes the depot specification in the system.
+    def delete_depot(depot)
+      depot = depot.depot if depot.is_a?(Models::Depot)
+      execute_method_no_body(:delete, "/depots/#{URI.encode(depot)}")
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client/files.rb

@@ -0,0 +1,30 @@
+require 'open-uri'
+require 'p4_web_api_client/models/dir'
+require 'p4_web_api_client/models/depot'
+require 'p4_web_api_client/models/file'
+
+module P4WebApiClient
+  class Client
+    # General file browsing method.
+    #
+    # The `path` parameter should be a directory location, starting with a
+    # depot location, e.g., `my_depot/dir1`.
+    #
+    # When path is empty, will return the list of depots.
+    def files(path = '')
+      unless path.empty?
+        path = path.split('/').map { |p| URI.encode(p) }.join('/')
+      end
+      arr = execute_method_no_body(:get, "/files/#{path}")
+      arr.map do |obj|
+        if obj.key?('DepotFile')
+          Models::File.new(obj)
+        elsif obj.key?('Dir')
+          Models::Dir.new(obj)
+        elsif obj.key?('Depot')
+          Models::Depot.new(obj)
+        end
+      end
+    end
+  end
+end

data/lib/p4_web_api_client/client/groups.rb

@@ -0,0 +1,41 @@
+require 'open-uri'
+require 'p4_web_api_client/models/group'
+
+module P4WebApiClient
+  class Client
+    # Array of Group objects stored in the system. Not all fields will be
+    # filled out (e.g., view).
+    def groups
+      arr = execute_method_no_body(:get, '/groups')
+      arr.map { |x|  Models::Group.new(x) }
+    end
+
+    # Returns the group instance indicated by the group name (or group object)
+    def group(group)
+      group = group.group if group.is_a?(Models::Group)
+      obj = execute_method_no_body(:get, "/groups/#{URI.encode(group)}")
+      Models::Group.new(obj)
+    end
+
+    # Creates a new group in the system.
+    def create_group(group)
+      group = Models::Group.new(group) unless group.is_a?(Models::Group)
+      execute_method_with_body(:post, '/groups', group.to_internal_hash)
+      true
+    end
+
+    # Updates the group specification.
+    def update_group(group)
+      execute_method_with_body(:put, "/groups/#{URI.encode(group.group)}",
+                               group.to_internal_hash)
+      true
+    end
+
+    # Deletes the group specification in the system.
+    def delete_group(group)
+      group = group.group if group.is_a?(Models::Group)
+      execute_method_no_body(:delete, "/groups/#{URI.encode(group)}")
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client/jobs.rb

@@ -0,0 +1,36 @@
+require 'open-uri'
+
+module P4WebApiClient
+  class Client
+    def jobs
+      execute_method_no_body(:get, '/jobs')
+    end
+
+    # Returns the array of jobs in the system. Each job model is simply a hash
+    # of string -> string values, since each system can very likely adjust
+    # job output.
+    def job(job_id)
+      execute_method_no_body(:get, "/jobs/#{URI.encode(job_id)}")
+    end
+
+    # Creates a new job in the system.
+    def create_job(job)
+      job['Job'] = 'new' unless job.key?('Job')
+      job['Status'] = 'open' unless job.key?('Status')
+      execute_method_with_body(:post, '/jobs', job)
+      true
+    end
+
+    # Updates the job specification.
+    def update_job(job)
+      execute_method_with_body(:put, "/jobs/#{URI.encode(job['Job'])}", job)
+      true
+    end
+
+    # Deletes the job specification in the system.
+    def delete_job(job_id)
+      execute_method_no_body(:delete, "/jobs/#{URI.encode(job_id)}")
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client/labels.rb

@@ -0,0 +1,41 @@
+require 'open-uri'
+require 'p4_web_api_client/models/label'
+
+module P4WebApiClient
+  class Client
+    # Array of Label objects stored in the system. Not all fields will be
+    # filled out (e.g., view).
+    def labels
+      arr = execute_method_no_body(:get, '/labels')
+      arr.map { |a| Models::Label.new(a) }
+    end
+
+    # Returns the label instance indicated by the label name (or label object)
+    def label(label)
+      label = label.label if label.is_a?(Models::Label)
+      obj = execute_method_no_body(:get, "/labels/#{URI.encode(label)}")
+      Models::Label.new(obj)
+    end
+
+    # Creates a new label in the system.
+    def create_label(label)
+      label = Models::Label.new(label) unless label.is_a?(Models::Label)
+      execute_method_with_body(:post, '/labels', label.to_internal_hash)
+      true
+    end
+
+    # Updates the label specification.
+    def update_label(label)
+      execute_method_with_body(:put, "/labels/#{URI.encode(label.label)}",
+                               label.to_internal_hash)
+      true
+    end
+
+    # Deletes the label specification in the system.
+    def delete_label(label)
+      label = label.label if label.is_a?(Models::Label)
+      execute_method_no_body(:delete, "/labels/#{URI.encode(label)}")
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client/protections.rb

@@ -0,0 +1,19 @@
+require 'p4_web_api_client/models/protections'
+
+module P4WebApiClient
+  class Client
+    # Fetch all protections in the system. Returns a single Protections
+    # instance.
+    def protections
+      obj = execute_method_no_body(:get, '/protections')
+      Models::Protections.new(obj)
+    end
+
+    # Updates the protections table based on the Protections instance passed in
+    def update_protections(protections)
+      execute_method_with_body(:put, '/protections',
+                               protections.to_internal_hash)
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client/run.rb

@@ -0,0 +1,38 @@
+require 'json'
+
+module P4WebApiClient
+  class Client
+    # Generic run command.
+    #
+    # First argument should always be the command, followed by command line
+    # arguments.
+    #
+    # Expect to always have an array of hashes as output.
+    def run(cmd, args = [])
+      params = arg_params(args)
+      params[:cmd] = cmd
+      execute_method_no_body(:get, '/run', params)
+    end
+
+    # Generic run command with and input body.
+    #
+    # The first argument is the general command, followed by the input data,
+    # then followed by additional command line arguments.
+    #
+    # Expect the output to always be an array of hashes.
+    def run_input(cmd, input, args = [])
+      params = arg_params(args)
+      params[:cmd] = cmd
+      execute_method_with_body(:post, '/run', params, input)
+    end
+
+    # Creates a hash and creates keys 'arg1', 'arg2', etc that points to
+    # the values in the arg_values array. This is basically only used by
+    # the run methods
+    def arg_params(arg_values)
+      params = {}
+      arg_values.each_index { |ii| params["arg#{ii + 1}"] = arg_values[ii] }
+      params
+    end
+  end
+end

data/lib/p4_web_api_client/client/servers.rb

@@ -0,0 +1,38 @@
+require 'open-uri'
+require 'p4_web_api_client/models/server'
+
+module P4WebApiClient
+  class Client
+    # Returns an array of Server objects representing people in the system.
+    def servers
+      arr = execute_method_no_body(:get, '/servers')
+      arr.map { |obj| Models::Server.new(obj) }
+    end
+
+    # Returns a P4WebApiClient::Models::Server for the login
+    def server(server)
+      server = server.server_id if server.is_a?(Models::Server)
+      obj = execute_method_no_body(:get, "/servers/#{URI.encode(server)}")
+      Models::Server.new(obj)
+    end
+
+    # Creates a new server in the system based on the Server instance
+    def create_server(server)
+      server = Models::Server.new(server) unless server.is_a?(Models::Server)
+      execute_method_with_body(:post, '/servers', server.to_internal_hash)
+      true
+    end
+
+    def update_server(server)
+      execute_method_with_body(:put, "/servers/#{URI.encode(server.server_id)}",
+                               server.to_internal_hash)
+      true
+    end
+
+    def delete_server(server)
+      server = server.server_id if server.is_a?(Models::Server)
+      execute_method_no_body(:delete, "/servers/#{URI.encode(server)}")
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client/streams.rb

@@ -0,0 +1,38 @@
+require 'open-uri'
+require 'p4_web_api_client/models/stream'
+
+module P4WebApiClient
+  class Client
+    # Returns an array of Stream objects representing people in the system.
+    def streams
+      arr = execute_method_no_body(:get, '/streams')
+      arr.map { |obj| Models::Stream.new(obj) }
+    end
+
+    # Returns a P4WebApiClient::Models::Stream for the login
+    def stream(stream)
+      stream = stream.stream_id if stream.is_a?(Models::Stream)
+      obj = execute_method_no_body(:get, "/streams/#{URI.encode(stream)}")
+      Models::Stream.new(obj)
+    end
+
+    # Creates a new stream in the system based on the Stream instance
+    def create_stream(stream)
+      stream = Models::Stream.new(stream) unless stream.is_a?(Models::Stream)
+      execute_method_with_body(:post, '/streams', stream.to_internal_hash)
+      true
+    end
+
+    def update_stream(stream)
+      execute_method_with_body(:put, "/streams/#{URI.encode(stream.stream)}",
+                               stream.to_internal_hash)
+      true
+    end
+
+    def delete_stream(stream)
+      stream = stream.stream_id if stream.is_a?(Models::Stream)
+      execute_method_no_body(:delete, "/streams/#{URI.encode(stream)}")
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client/triggers.rb

@@ -0,0 +1,18 @@
+require 'p4_web_api_client/models/triggers'
+
+module P4WebApiClient
+  class Client
+    # Returns a single Triggers object representing the entire triggers table
+    # of the system. (See Triggers model for more details.)
+    def triggers
+      obj = execute_method_no_body(:get, '/triggers')
+      Models::Triggers.new(obj)
+    end
+
+    # Update the triggers table using the Triggers model instance
+    def update_triggers(triggers)
+      execute_method_with_body(:put, '/triggers', triggers.to_internal_hash)
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client/users.rb

@@ -0,0 +1,38 @@
+require 'open-uri'
+require 'p4_web_api_client/models/user'
+
+module P4WebApiClient
+  class Client
+    # Returns an array of User objects representing people in the system.
+    def users
+      arr = execute_method_no_body(:get, '/users')
+      arr.map { |obj| Models::User.new(obj) }
+    end
+
+    # Returns a P4WebApiClient::Models::User for the login
+    def user(user)
+      user = user.user if user.is_a?(Models::User)
+      obj = execute_method_no_body(:get, "/users/#{URI.encode(user)}")
+      Models::User.new(obj)
+    end
+
+    # Creates a new user in the system based on the User instance
+    def create_user(user)
+      user = Models::User.new(user) unless user.is_a?(Models::User)
+      execute_method_with_body(:post, '/users', user.to_internal_hash)
+      true
+    end
+
+    def update_user(user)
+      execute_method_with_body(:put, "/users/#{URI.encode(user.user)}",
+                               user.to_internal_hash)
+      true
+    end
+
+    def delete_user(user)
+      user = user.user if user.is_a?(Models::User)
+      execute_method_no_body(:delete, "/users/#{URI.encode(user)}")
+      true
+    end
+  end
+end

data/lib/p4_web_api_client/client.rb

@@ -0,0 +1,86 @@
+
+require 'json'
+require 'open-uri'
+require 'p4_web_api_client/version'
+require 'p4_web_api_client/errors'
+require 'p4_web_api_client/models'
+
+module P4WebApiClient
+  # Each client instance represents a single 'session' against the P4 Web API.
+  #
+  # Access the client object like a typical I/O object - use open().
+  #
+  # Most methods assert that the response is OK. When not OK, we throw an
+  # exception. See P4WebApiClient::Errors for the different exception classes.
+  #
+  # Many methods return 'model' objects that are basically 'dumb old objects',
+  # i.e., editing models will not make edits to the Perforce system. All
+  # modifying methods lie within this Client object, which typically binds to
+  # a single RPC call.
+  #
+  # TODO: URL to online documentation
+  class Client
+    # This is an instance of P4WebApiClient::Connection
+    attr_accessor :connection
+
+    # The host_url is just the method and host, e.g., http://example.com/
+    #
+    # The P4 Web API context should be set if you don't access URLs like
+    # POST http://example.com/p4/v1/sessions.
+    #
+    # Any client created via Client.new should take care to call close().
+    #
+    def initialize(connection)
+      @connection = connection
+    end
+
+    def close
+      connection.run_method_no_body(:delete,
+                                    "/sessions/#{connection.session_token}")
+    end
+
+    # Provides standard I/O style interface, where when called in a block,
+    # will automatically close() the client when done. Otherwise, your code
+    # should call client.close() manually.
+    def self.open(connection)
+      client = Client.new(connection)
+
+      if block_given?
+        yield client
+      else
+        return client
+      end
+    ensure
+      client.close if block_given? && client
+    end
+
+    private
+
+    def execute_method_no_body(method, path, params = nil)
+      response = connection.run_method_no_body(method, path, params)
+      JSON.parse(response.body) if response.body && !response.body.empty?
+    end
+
+    def execute_method_with_body(method, path, params = nil, body = nil)
+      response = connection.run_method_with_body(method, path, params, body)
+      JSON.parse(response.body) if response.body && !response.body.empty?
+    end
+  end
+end
+
+# The Client class has quite a few methods that deal with the different models
+# occasionally in subtly different ways.
+require 'p4_web_api_client/client/branches'
+require 'p4_web_api_client/client/changes'
+require 'p4_web_api_client/client/clients'
+require 'p4_web_api_client/client/depots'
+require 'p4_web_api_client/client/files'
+require 'p4_web_api_client/client/groups'
+require 'p4_web_api_client/client/jobs'
+require 'p4_web_api_client/client/labels'
+require 'p4_web_api_client/client/protections'
+require 'p4_web_api_client/client/run'
+require 'p4_web_api_client/client/servers'
+require 'p4_web_api_client/client/streams'
+require 'p4_web_api_client/client/triggers'
+require 'p4_web_api_client/client/users'

data/lib/p4_web_api_client/connection.rb

@@ -0,0 +1,98 @@
+
+require 'faraday'
+require 'faraday_middleware'
+
+module P4WebApiClient
+  # Adds common configuration to the Faraday connection, like, the host name,
+  # version, and context prefixes.
+  class Connection
+    attr_accessor :login, :prefix, :session_token
+
+    # See the options for Faraday.new, plus, the following fields:
+    # - :login
+    # - :password
+    # - :prefix - defaults to '/v1'
+    def initialize(options = {})
+      local_opts = [:login, :password, :prefix]
+      conn_options = options.select { |k| !local_opts.include?(k) }
+
+      @conn = Faraday.new(conn_options)
+
+      @session_token = nil
+      @login = options[:login]
+      @prefix = options.key?(:prefix) ? options[:prefix] : '/v1'
+
+      # When we're not initialized with a password, we may be on a insecure
+      # server, so don't even log in.
+      if options[:password] && !Connection.p4_ticket?(options[:password])
+        response = @conn.post(path_for('/sessions'),
+                              login: @login,
+                              password: options[:password])
+        assert_ok(response)
+
+        @session_token = response.body
+      else
+        # When the password looks like a p4 ticket (or maybe it's empty),
+        # we don't generate the session token
+        @session_token = options[:password] || ''
+      end
+      @conn.basic_auth(login, session_token)
+    end
+
+    def self.p4_ticket?(str)
+      /^[a-zA-Z0-9]{32,}$/.match(str) != nil
+    end
+
+    def run_method_no_body(method, path, params = nil)
+      path = path_for(path)
+
+      response = @conn.send(method, path, params)
+      assert_ok(response)
+      response
+    end
+
+    def run_method_with_body(method, path, params = nil, body = nil)
+      if !body && params
+        body = params
+        params = nil
+      end
+
+      path = path_for(path)
+
+      if params
+        params_hash = Faraday::Utils::ParamsHash.new
+        params_hash.merge!(params)
+        path += "?#{params_hash.to_query}"
+      end
+
+      response = @conn.send(method, path, body)
+      assert_ok(response)
+      response
+    end
+
+    # Basically just prepends the prefix to our subpath, typically, '/p4'.
+    def path_for(subpath)
+      if @prefix.empty?
+        subpath
+      else
+        File.join(@prefix, subpath)
+      end
+    end
+
+    # Raises an error when the response is not 200. Some errors may have
+    # diagnostic information in the response body, so we pass that on as well
+    def assert_ok(response)
+      return unless response.status >= 400
+      if response.status == 403
+        fail Errors::Unauthenticated.new, 'Illegal login or password'
+      elsif response.status == 404
+        fail Errors::ResourceNotFound.new, 'Required resource not found'
+      elsif response.status == 500 && response.body
+        fail Errors::PerforceProblem.new(JSON.parse(response.body)),
+             'Unknown issue from the Perforce server'
+      else
+        fail Errors::ServerError.new, 'Unknown problem'
+      end
+    end
+  end
+end