p4_web_api 2014.2.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3a33dc12a8f5e6304cf6408d9aa711b206173a00
+  data.tar.gz: e9a9c2af51c18f19a22f8267cdade878f69b40e8
+SHA512:
+  metadata.gz: 2864edc78108d670eaabd5e4b0e868a46950c3b2cffcb62c9920b0e09ba8c4827036359869b70ddddb4fbf1b2f4e4cc8cc7f4fa4627c6d7026897378488564f4
+  data.tar.gz: a1dc0543c17c29071686891eec720d25d0987aa4e5a4e9750b698cd57b8c06c474368720b94e30201de7773449a6fb5898bffb5d0b876ebe3ec18a583b88b4cc

data/bin/p4_web_api

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+lib_path = File.expand_path('../../lib/p4_web_api.rb', __FILE__)
+require lib_path
+P4WebAPI::App.run!

data/lib/p4_web_api.rb

@@ -0,0 +1,700 @@
+# Copyright (c) 2014 Perforce Software, Inc.  All rights reserved.
+# vim:ts=2:sw=2:et:si:ai:
+# p4_web_api.rb
+#
+# Setup
+# -----
+#
+# Avast, your webserver should map /p4 to the root of this application. This
+# is easily done in rails with the following route:
+#
+#    mount P4WebAPI, at: '/p4'
+#
+# You will need a p4_web_api.yml configuration file created as well, to indicate
+# where security token data is stored, and where the Perforce server lies.
+
+require 'sinatra/base'
+require 'sinatra/json'
+require 'sinatra/config_file'
+require 'rack/parser'
+
+require 'p4_web_api/version'
+require 'p4_web_api/auth'
+require 'p4_web_api/p4_util'
+
+# The P4WebAPI is our namespace for the web application.
+#
+# See P4WebAPI::App for most of the implemented methods. In general each method
+# maps to a P4Ruby call.
+#
+# The other modules under the P4WebAPI are generally helpers, like the
+# Authentication middleware, or P4Util conventions around using P4Ruby.
+module P4WebAPI
+  # This web application is mostly a lightweight way of connecting the tagged
+  # output via P4Ruby to JSON clients can consume relatively simply.
+  class App < Sinatra::Base
+    register Sinatra::ConfigFile
+
+    # Inject Rack::Parser into the middleware stack so that it
+    # automatically parses json bodies in post requests into the params
+    # array.
+    use Rack::Parser, content_types: {
+      'application/json' => proc { |body| ::MultiJson.decode body }
+    }
+
+    use P4WebAPI::AuthMiddleware,
+        unauthenticated_paths: ['/v1/sessions'],
+        settings: settings
+
+    # Without this set, the return content type is always text/html
+    before do
+      content_type 'application/json'
+    end
+
+    configure do
+      set(:p4, 'host' => 'localhost', 'port' => '1666')
+      set(:token_path, '/tmp/p4_web_api/tokens')
+
+      set(:run_get_blacklist, %w(add change changelist clean copy cstat
+                                 delete diff edit flush have integ integrate
+                                 lock login logout move reconcile rename
+                                 reopen resolve resolved revert shelve submit
+                                 sync unlock unshelve where
+                              ))
+
+      # To allow other rack middleware to decide P4_HOST and P4_PORT,
+      # allow_env_p4_config must be true, otherwise, we'll only use the standard
+      # rack configuration mechanism.
+      set(:allow_env_p4_config, false)
+
+      # This is odd, but with some of the project restructuring,
+      # this setting marked error.rb as the 'app_file'
+      set(:app_file, __FILE__)
+
+      # When set to true, we'll run most of the output through a 'normalization'
+      # set of rules. We don't do this for the run methods, but most fields
+      # should appear capitalized, and output dates should all show up in the
+      # standard epoch timestamp
+      set(:normalize_output, true)
+
+      set :raise_errors, :environment == :test
+      set :dump_errors, :environment == :development
+      set :show_exceptions, :environment == :development
+
+      enable :logging
+
+      config_path = if ENV.key?('P4_WEB_API_CONFIG')
+                      ENV['P4_WEB_API_CONFIG']
+                    else
+                      'p4_web_api.yml'
+                    end
+
+      config_file config_path if File.exist?(config_path)
+    end
+
+    P4WebAPI::Auth.validate_token_dir(settings.token_path)
+
+    helpers do
+      # A block helper that uses the authentication credentials to create the p4
+      # connection
+      def open_p4(&block)
+        options = {
+          user: env['AUTH_CREDENTIALS'].first,
+          password: P4Util.resolve_password(env, settings),
+          host: P4Util.resolve_host(env, settings),
+          port: P4Util.resolve_port(env, settings)
+        }
+
+        charset = P4Util.resolve_charset(env, settings)
+        options[:charset] = charset if charset
+
+        P4Util.open(options, &block)
+      end
+
+    end
+
+    error do
+      err = env['sinatra.error']
+
+      if err.is_a?(P4Exception)
+        # Can happen when we're not passing a block to
+        # open_p4. Convert to a P4WebAPI error. This is not ideal
+        # as it always uses the same code, but then we have no idea
+        # what actually happened here.
+
+        err = P4WebAPI::P4Error.default_error(err.to_s)
+
+        # Fall through...
+      end
+
+      if err.is_a?(P4WebAPI::P4Error)
+        if err.message_code == 7480 || err.message_code == 7189
+          halt 401
+        else
+          return {
+            MessageCode: err.message_code,
+            MessageSeverity: err.message_severity,
+            MessageText: err.message_text
+          }.to_json
+        end
+      end
+      fail err
+    end
+
+    def to_msg(message)
+      {
+        MessageCode: message.msgid,
+        MessageSeverity: message.severity,
+        MessageText: message.to_s
+      }
+    end
+
+    # Will fetch the system offset based on the server date.
+    #
+    # If allow_env_p4_config is true, we don't cache. Each request could come
+    # in from a new server, and the different servers may have different
+    # offsets.
+    def offset
+      if settings.allow_env_p4_config
+        fetch_offset
+      else
+        @offset ||= fetch_offset
+      end
+    end
+
+    def fetch_offset
+      offset = nil
+      open_p4 do |p4|
+        results = p4.run_info
+        offset = P4Util.p4_date_offset(results[0]['serverDate'])
+      end
+      offset
+    end
+
+    @normalizers = {}
+
+    class << self
+      attr_accessor :normalizers
+    end
+
+    # It's assumed that these are typically used to find the different spec
+    # types within typical requests.
+    def method_missing(method, *args)
+      return unless method.to_s =~ /^normalize_(.*)/
+
+      spec_type = Regexp.last_match[1]
+      unless self.class.normalizers.key?(spec_type)
+        self.class.normalizers[spec_type] = P4Util.normalizer(spec_type, offset)
+      end
+      self.class.normalizers[spec_type].call(*args)
+    end
+
+    # Authentication methods
+    # See also: https://confluence.perforce.com:8443/display/WS/Authentication+in+Web+Services
+
+    # Creates a sign-in session for the user.
+    #
+    # This session returns a token that should be used as the password in basic
+    # authentication for the user later.
+    post '/v1/sessions' do
+      login = params[:login]
+      password = params[:password] # may be a p4 ticket
+
+      token = nil
+
+      options = {
+        user: login,
+        password: password,
+        host: settings.p4['host'],
+        port: settings.p4['port']
+      }
+      options[:charset] = settings.p4['charset'] if settings.p4.key?('charset')
+
+      P4Util.open(options) do |p4|
+        token = Auth.create_session(p4, password, settings)
+      end
+
+      # We signal a 401 when login/passwords are generally invalid. Since this
+      # is an unauthenticated request, you shouldn't be able to tell if the
+      # login doesn't exist or the password is incorrect.
+      halt 401 unless token
+
+      content_type 'text/plain'
+      return token
+    end
+
+    # I'm not sure if we should ensure the token being deleted is the token
+    # being authenticated against. That's not being checked for the time being.
+    delete '/v1/sessions/:token' do |token|
+      P4WebAPI::Auth.delete_session(token, settings)
+      ''
+    end
+
+    # Generic 'do a perforce command' methods.
+    #
+    # These do not ensure true REST-ful style behavior, but are really just
+    # "hey use HTTP to interact with Perforce".
+
+    get '/v1/run' do
+
+      cmd = params[:cmd]
+
+      args = params.select { |key, _| key.start_with?('arg') }
+             .map { |_, value| value }
+
+      if settings.run_get_blacklist.include?(cmd)
+        halt 403, { MessageCode: 15_360,
+                    MessageText: "#{cmd} not allowed in web api",
+                    MessageSeverity: :ERROR }.to_json
+      end
+
+      results = nil
+      messages = nil
+
+      open_p4 do |p4|
+        results = p4.run(cmd, *args)
+        messages = p4.messages
+      end
+
+      if messages && messages.length > 0
+        messages.map { |m| to_msg(m) }.to_json
+      elsif results
+        results.to_json
+      end
+
+    end
+
+    post '/v1/run' do
+      cmd = params[:cmd]
+
+      args = params.select { |key, _| key.start_with?('arg') }
+             .map { |_, value| value }
+
+      # Uses the same blacklist as GET which generally makes sense, since we'll
+      # only really be concerned about client workspace usage on this server.
+      if settings.run_get_blacklist.include?(cmd)
+        halt 403, { MessageCode: 15_360,
+                    MessageText: "#{cmd} not allowed in web api",
+                    MessageSeverity: :ERROR }.to_json
+      end
+
+      messages = nil
+
+      open_p4 do |p4|
+        p4.input = filter_params(params)
+        p4.run(cmd, args)
+        messages = p4.messages
+      end
+
+      messages.map { |m| to_msg(m) }.to_json if messages
+    end
+
+    # Convenience method to the 'run' mechanism for typical browsing purposes.
+    #
+    # Unlike just standard run commands, this will select either the 'depots' or
+    # 'files' and 'dirs' commands for a single directory level at a time.
+
+    # Special depots only variant
+    get '/v1/files' do
+      results = nil
+
+      open_p4 do |p4|
+        results = p4.run_depots
+      end
+
+      normalize_depots(results) if settings.normalize_output
+
+      results.to_json
+    end
+
+    # General browsing variation.
+    get '/v1/files/*' do
+      dirs = params[:splat].select { |x| !x.empty? }
+
+      results = nil
+
+      open_p4 do |p4|
+        if dirs.empty?
+          results = p4.run_depots
+          normalize_depots(results) if settings.normalize_output
+        else
+          selector = '//' + dirs.join('/') + '/*'
+          files_results = p4.run_files(selector)
+          normalize_files(files_results) if settings.normalize_output
+          dirs_results = p4.run_dirs(selector)
+          normalize_dirs(dirs_results) if settings.normalize_output
+          results = files_results + dirs_results
+        end
+      end
+
+      results.to_json
+    end
+
+    # Convenience method to list changelist metadata with some common filtering
+    # options.
+    #
+    # parameters:
+    # - `max` = number
+    # - `status` = pending|submitted|shelved
+    # - `user` = [login]
+    # - `files` = pattern
+    get '/v1/changes' do
+      max = params['max'] if params.key?('max')
+      status = params['status'] if params.key?('status')
+      user = params['user'] if params.key?('user')
+      files = params['files'] if params.key?('files')
+
+      results = nil
+
+      open_p4 do |p4|
+        args = ['changes']
+
+        args.push('-m', max) if max
+        args.push('-s', status) if status
+        args.push('-u', user) if user
+        args.push(files) if files
+
+        results = p4.run(*args)
+      end
+
+      normalize_changes(results) if settings.normalize_output
+
+      results.to_json
+    end
+
+    # Methods to manipulate the protections table. This blindly assumes you
+    # indeed have superuser privileges.
+
+    # Just list all protections
+    get '/v1/protections' do
+      protects = nil
+      open_p4 do |p4|
+        protects = p4.run_protect('-o').first
+      end
+
+      normalize_protections(results) if settings.normalize_output
+
+      protects.to_json
+    end
+
+    # Update protections
+    put '/v1/protections' do
+      protects = {
+        'Protections' => params['Protections']
+      }
+
+      open_p4 do |p4|
+        p4.input = protects
+        p4.run_protect('-i')
+      end
+
+      ''
+    end
+
+    # Methods to adjust the triggers table.
+
+    get '/v1/triggers' do
+      triggers = nil
+      open_p4 do |p4|
+        triggers = p4.run_triggers('-o').first
+      end
+
+      normalize_triggers(results) if settings.normalize_output
+
+      triggers.to_json
+    end
+
+    # Update protections
+    put '/v1/triggers' do
+      triggers = {
+        'Triggers' => params['Triggers']
+      }
+
+      open_p4 do |p4|
+        p4.input = triggers
+        p4.run_triggers('-i')
+      end
+
+      ''
+    end
+
+    # Generate CRUD methods for each 'spec' type
+    #
+
+    set(:is_spec) do |_x|
+      condition do
+        path_info = env['PATH_INFO']
+
+        matches = %r{^/v1/(?<spec_type>\w+)}.match(path_info)
+        if matches
+          spec_type = matches[:spec_type]
+          return (spec_type == 'branches' ||
+              spec_type == 'clients' ||
+              spec_type == 'depots' ||
+              spec_type == 'groups' ||
+              spec_type == 'jobs' ||
+              spec_type == 'labels' ||
+              # No protects here: the usage is pretty different from the other
+              # spec mechanisms
+              spec_type == 'servers'
+          # No streams, triggers, or users here: it does not work like other
+          # specs, so these method implementations don't quite work.
+          )
+        end
+        false
+      end
+    end
+
+    # Provide a generic collection accessor for each of the specs.
+    get '/v1/:spec_type', is_spec: true do |spec_type|
+      results = nil
+
+      open_p4 do |p4|
+        results = p4.run(spec_type)
+      end
+
+      send("normalize_#{spec_type}", results) if settings.normalize_output
+      P4Util.collate_group_results(results) if settings.normalize_output &&
+                                               spec_type == 'groups'
+
+      results.to_json
+    end
+
+    # Provide a generic output accessor for each spec
+    get '/v1/:spec_type/:id', is_spec: true do |spec_type, id|
+      results = nil
+
+      open_p4 do |p4|
+        results = p4.run(P4Util.singular(spec_type), '-o', id)
+      end
+
+      send("normalize_#{spec_type}", results) if settings.normalize_output
+
+      results[0].to_json
+    end
+
+    # This is our generic "add" mechanism for each type.
+    #
+    # It's assumed that the client understands the requirements of each spec
+    # type.
+    post '/v1/:spec_type', is_spec: true do |spec_type|
+      results = nil
+
+      open_p4 do |p4|
+        method_name = "save_#{P4Util.singular(spec_type)}".to_sym
+        results = p4.send(method_name, params)
+      end
+
+      # In general, the params use the name of the spec as a capitalized
+      # parameter in the singular form.
+      if spec_type == 'servers'
+        id_prop = 'ServerID'
+      else
+        id_prop = P4Util.singular(spec_type).capitalize
+      end
+      id = nil
+      if results.is_a?(Array) &&
+         results.length > 0 &&
+         /Job .* saved/.match(results[0])
+        # special "Job" variant to grab the ID out of the results output
+        id = /Job (.*) saved/.match(results[0])[1]
+      elsif params.key?(id_prop)
+        id = params[id_prop]
+      elsif params.key?(id_prop.to_sym)
+        id = params[id_prop.to_sym]
+      end
+
+      if id
+        redirect "/v1/#{spec_type}/#{id}"
+      else
+        halt 400, "Did not locate #{id_prop} in params"
+      end
+
+    end
+
+    # An 'update' mechanism for each spec type.
+    put '/v1/:spec_type/:id', is_spec: true do |spec_type, id|
+      open_p4 do |p4|
+        singular = P4Util.singular(spec_type)
+        spec = p4.run(singular, '-o', id)[0]
+
+        spec = spec.merge(filter_params(params))
+
+        method_name = "save_#{singular}".to_sym
+        p4.send(method_name, spec)
+      end
+
+      ''
+    end
+
+    delete '/v1/:spec_type/:id', is_spec: true do |spec_type, id|
+      open_p4 do |p4|
+        method_name = "delete_#{P4Util.singular(spec_type)}".to_sym
+        p4.send(method_name, id)
+      end
+
+      ''
+    end
+
+    # List all users registered in the server
+    get '/v1/users' do
+      results = nil
+
+      open_p4 do |p4|
+        results = p4.run_users
+      end
+
+      normalize_users(results) if settings.normalize_output
+
+      results.to_json
+    end
+
+    # Create a new user
+    post '/v1/users' do
+      open_p4 do |p4|
+        p4.save_user(params, '-f')
+      end
+
+      login = params['User']
+
+      redirect "/v1/users/#{login}"
+    end
+
+    get '/v1/users/:user' do |user|
+      results = nil
+
+      open_p4 do |p4|
+        results = p4.run_user('-o', user)
+      end
+
+      normalize_users(results) if settings.normalize_output
+
+      if results.empty?
+        halt 404
+      else
+        results[0].to_json
+      end
+    end
+
+    # 'Update' the user.
+    put '/v1/users/:user' do |user|
+      open_p4 do |p4|
+        results = p4.run_user('-o', user)
+
+        if results.empty?
+          halt 404
+          return
+        end
+
+        spec = results[0]
+        spec = spec.merge(filter_params(params))
+
+        spec['User'] = user unless spec.key?('User')
+
+        p4.save_user(spec, '-f')
+      end
+
+      # Avoid 'user jdoe saved' message from going out
+      ''
+    end
+
+    # Delete the user.
+    delete '/v1/users/:user' do |user|
+      open_p4 do |p4|
+        p4.run_user('-f', '-d', user)
+      end
+
+      # If you're deleting yourself (ragequitting via API) remove thy session
+      if user == env['AUTH_CREDENTIALS'].first
+        token = env['AUTH_CREDENTIALS'].last
+        P4WebAPI::Auth.delete_session(token, settings)
+      end
+    end
+
+    # Stream manipulation
+    #
+    # Streams are a little different from other spec types, in that the singluar
+    # 'stream' is identified by a depot-style path, as opposed to kind of a
+    # name. (And since our paths start with two slashes, we ignore those).
+
+    get '/v1/streams' do
+      streams = nil
+
+      open_p4 do |p4|
+        streams = p4.run_streams
+      end
+
+      normalize_streams(streams) if settings.normalize_output
+
+      streams.to_json
+    end
+
+    # Creates a new stream
+    post '/v1/streams' do
+      open_p4 do |p4|
+        p4.save_stream(filter_params(params))
+      end
+
+      stream = params['Stream']
+
+      sub_path = stream[2..-1]
+
+      redirect "/v1/streams/#{sub_path}"
+    end
+
+    get '/v1/streams/*' do
+      sub_path = params[:splat].join('')
+
+      stream = "//#{sub_path}"
+
+      results = nil
+
+      open_p4 do |p4|
+        results = p4.run_stream('-o', stream)
+      end
+
+      normalize_streams(results) if settings.normalize_output
+
+      results[0].to_json
+    end
+
+    put '/v1/streams/*' do
+      sub_path = params[:splat].join('')
+
+      stream = "//#{sub_path}"
+
+      open_p4 do |p4|
+        spec = p4.run_stream('-o', stream)[0]
+
+        spec = spec.merge(filter_params(params))
+
+        p4.save_stream(spec, '-f')
+      end
+
+      ''
+    end
+
+    delete '/v1/streams/*' do
+      sub_path = params[:splat].join('')
+
+      stream = "//#{sub_path}"
+
+      open_p4 do |p4|
+        p4.run_stream('-d', stream)
+      end
+
+      ''
+    end
+
+    # Basically a "blacklist" of things we know the frameworks going to add to
+    # the params array we don't want to pass on to the p4 command sets for spec
+    # input
+    def filter_params(params)
+      params.select do |k, _v|
+        k != 'spec_type' && k != 'id' && k != 'splat' && k != 'captures'
+      end
+    end
+
+    run! if app_file == $PROGRAM_NAME
+  end
+end