xref: /external/chromium-trace/catapult/third_party/gsutil/third_party/protorpc/protorpc/webapp/service_handlers.py

#!/usr/bin/env python
#
# Copyright 2010 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

"""Handlers for remote services.

This module contains classes that may be used to build a service
on top of the App Engine Webapp framework.

The services request handler can be configured to handle requests in a number
of different request formats.  All different request formats must have a way
to map the request to the service handlers defined request message.Message
class.  The handler can also send a response in any format that can be mapped
from the response message.Message class.

Participants in an RPC:

  There are four classes involved with the life cycle of an RPC.

    Service factory: A user-defined service factory that is responsible for
      instantiating an RPC service.  The methods intended for use as RPC
      methods must be decorated by the 'remote' decorator.

    RPCMapper: Responsible for determining whether or not a specific request
      matches a particular RPC format and translating between the actual
      request/response and the underlying message types.  A single instance of
      an RPCMapper sub-class is required per service configuration.  Each
      mapper must be usable across multiple requests.

    ServiceHandler: A webapp.RequestHandler sub-class that responds to the
      webapp framework.  It mediates between the RPCMapper and service
      implementation class during a request.  As determined by the Webapp
      framework, a new ServiceHandler instance is created to handle each
      user request.  A handler is never used to handle more than one request.

    ServiceHandlerFactory: A class that is responsible for creating new,
      properly configured ServiceHandler instance for each request.  The
      factory is configured by providing it with a set of RPCMapper instances.
      When the Webapp framework invokes the service handler, the handler
      creates a new service class instance.  The service class instance is
      provided with a reference to the handler.  A single instance of an
      RPCMapper sub-class is required to configure each service.  Each mapper
      instance must be usable across multiple requests.

RPC mappers:

  RPC mappers translate between a single HTTP based RPC protocol and the
  underlying service implementation.  Each RPC mapper must configured
  with the following information to determine if it is an appropriate
  mapper for a given request:

    http_methods: Set of HTTP methods supported by handler.

    content_types: Set of supported content types.

    default_content_type: Default content type for handler responses.

  Built-in mapper implementations:

    URLEncodedRPCMapper: Matches requests that are compatible with post
      forms with the 'application/x-www-form-urlencoded' content-type
      (this content type is the default if none is specified.  It
      translates post parameters into request parameters.

    ProtobufRPCMapper: Matches requests that are compatible with post
      forms with the 'application/x-google-protobuf' content-type.  It
      reads the contents of a binary post request.

Public Exceptions:
  Error: Base class for service handler errors.
  ServiceConfigurationError: Raised when a service not correctly configured.
  RequestError: Raised by RPC mappers when there is an error in its request
    or request format.
  ResponseError: Raised by RPC mappers when there is an error in its response.
"""
import six

__author__ = 'rafek@google.com (Rafe Kaplan)'

import six.moves.http_client
import logging

from .google_imports import webapp
from .google_imports import webapp_util
from .. import messages
from .. import protobuf
from .. import protojson
from .. import protourlencode
from .. import registry
from .. import remote
from .. import util
from . import forms

__all__ = [
    'Error',
    'RequestError',
    'ResponseError',
    'ServiceConfigurationError',

    'DEFAULT_REGISTRY_PATH',

    'ProtobufRPCMapper',
    'RPCMapper',
    'ServiceHandler',
    'ServiceHandlerFactory',
    'URLEncodedRPCMapper',
    'JSONRPCMapper',
    'service_mapping',
    'run_services',
]


class Error(Exception):
  """Base class for all errors in service handlers module."""


class ServiceConfigurationError(Error):
  """When service configuration is incorrect."""


class RequestError(Error):
  """Error occurred when building request."""


class ResponseError(Error):
  """Error occurred when building response."""


_URLENCODED_CONTENT_TYPE = protourlencode.CONTENT_TYPE
_PROTOBUF_CONTENT_TYPE = protobuf.CONTENT_TYPE
_JSON_CONTENT_TYPE = protojson.CONTENT_TYPE

_EXTRA_JSON_CONTENT_TYPES = ['application/x-javascript',
                             'text/javascript',
                             'text/x-javascript',
                             'text/x-json',
                             'text/json',
                            ]

# The whole method pattern is an optional regex.  It contains a single
# group used for mapping to the query parameter.  This is passed to the
# parameters of 'get' and 'post' on the ServiceHandler.
_METHOD_PATTERN = r'(?:\.([^?]*))?'

DEFAULT_REGISTRY_PATH = forms.DEFAULT_REGISTRY_PATH


class RPCMapper(object):
  """Interface to mediate between request and service object.

  Request mappers are implemented to support various types of
  RPC protocols.  It is responsible for identifying whether a
  given request matches a particular protocol, resolve the remote
  method to invoke and mediate between the request and appropriate
  protocol messages for the remote method.
  """

  @util.positional(4)
  def __init__(self,
               http_methods,
               default_content_type,
               protocol,
               content_types=None):
    """Constructor.

    Args:
      http_methods: Set of HTTP methods supported by mapper.
      default_content_type: Default content type supported by mapper.
      protocol: The protocol implementation.  Must implement encode_message and
        decode_message.
      content_types: Set of additionally supported content types.
    """
    self.__http_methods = frozenset(http_methods)
    self.__default_content_type = default_content_type
    self.__protocol = protocol

    if content_types is None:
      content_types = []
    self.__content_types = frozenset([self.__default_content_type] +
                                     content_types)

  @property
  def http_methods(self):
    return self.__http_methods

  @property
  def default_content_type(self):
    return self.__default_content_type

  @property
  def content_types(self):
    return self.__content_types

  def build_request(self, handler, request_type):
    """Build request message based on request.

    Each request mapper implementation is responsible for converting a
    request to an appropriate message instance.

    Args:
      handler: RequestHandler instance that is servicing request.
        Must be initialized with request object and been previously determined
        to matching the protocol of the RPCMapper.
      request_type: Message type to build.

    Returns:
      Instance of request_type populated by protocol buffer in request body.

    Raises:
      RequestError if the mapper implementation is not able to correctly
      convert the request to the appropriate message.
    """
    try:
      return self.__protocol.decode_message(request_type, handler.request.body)
    except (messages.ValidationError, messages.DecodeError) as err:
      raise RequestError('Unable to parse request content: %s' % err)

  def build_response(self, handler, response, pad_string=False):
    """Build response based on service object response message.

    Each request mapper implementation is responsible for converting a
    response message to an appropriate handler response.

    Args:
      handler: RequestHandler instance that is servicing request.
        Must be initialized with request object and been previously determined
        to matching the protocol of the RPCMapper.
      response: Response message as returned from the service object.

    Raises:
      ResponseError if the mapper implementation is not able to correctly
      convert the message to an appropriate response.
    """
    try:
      encoded_message = self.__protocol.encode_message(response)
    except messages.ValidationError as err:
      raise ResponseError('Unable to encode message: %s' % err)
    else:
      handler.response.headers['Content-Type'] = self.default_content_type
      handler.response.out.write(encoded_message)


class ServiceHandlerFactory(object):
  """Factory class used for instantiating new service handlers.

  Normally a handler class is passed directly to the webapp framework
  so that it can be simply instantiated to handle a single request.
  The service handler, however, must be configured with additional
  information so that it knows how to instantiate a service object.
  This class acts the same as a normal RequestHandler class by
  overriding the __call__ method to correctly configures a ServiceHandler
  instance with a new service object.

  The factory must also provide a set of RPCMapper instances which
  examine a request to determine what protocol is being used and mediates
  between the request and the service object.

  The mapping of a service handler must have a single group indicating the
  part of the URL path that maps to the request method.  This group must
  exist but can be optional for the request (the group may be followed by
  '?' in the regular expression matching the request).

  Usage:

    stock_factory = ServiceHandlerFactory(StockService)
    ... configure stock_factory by adding RPCMapper instances ...

    application = webapp.WSGIApplication(
        [stock_factory.mapping('/stocks')])

  Default usage:

    application = webapp.WSGIApplication(
        [ServiceHandlerFactory.default(StockService).mapping('/stocks')])
  """

  def __init__(self, service_factory):
    """Constructor.

    Args:
      service_factory: Service factory to instantiate and provide to
        service handler.
    """
    self.__service_factory = service_factory
    self.__request_mappers = []

  def all_request_mappers(self):
    """Get all request mappers.

    Returns:
      Iterator of all request mappers used by this service factory.
    """
    return iter(self.__request_mappers)

  def add_request_mapper(self, mapper):
    """Add request mapper to end of request mapper list."""
    self.__request_mappers.append(mapper)

  def __call__(self):
    """Construct a new service handler instance."""
    return ServiceHandler(self, self.__service_factory())

  @property
  def service_factory(self):
    """Service factory associated with this factory."""
    return self.__service_factory

  @staticmethod
  def __check_path(path):
    """Check a path parameter.

    Make sure a provided path parameter is compatible with the
    webapp URL mapping.

    Args:
      path: Path to check.  This is a plain path, not a regular expression.

    Raises:
      ValueError if path does not start with /, path ends with /.
    """
    if path.endswith('/'):
      raise ValueError('Path %s must not end with /.' % path)

  def mapping(self, path):
    """Convenience method to map service to application.

    Args:
      path: Path to map service to.  It must be a simple path
        with a leading / and no trailing /.

    Returns:
      Mapping from service URL to service handler factory.
    """
    self.__check_path(path)

    service_url_pattern = r'(%s)%s' % (path, _METHOD_PATTERN)

    return service_url_pattern, self

  @classmethod
  def default(cls, service_factory, parameter_prefix=''):
    """Convenience method to map default factory configuration to application.

    Creates a standardized default service factory configuration that pre-maps
    the URL encoded protocol handler to the factory.

    Args:
      service_factory: Service factory to instantiate and provide to
        service handler.
      method_parameter: The name of the form parameter used to determine the
        method to invoke used by the URLEncodedRPCMapper.  If None, no
        parameter is used and the mapper will only match against the form
        path-name.  Defaults to 'method'.
      parameter_prefix: If provided, all the parameters in the form are
        expected to begin with that prefix by the URLEncodedRPCMapper.

    Returns:
      Mapping from service URL to service handler factory.
    """
    factory = cls(service_factory)

    factory.add_request_mapper(ProtobufRPCMapper())
    factory.add_request_mapper(JSONRPCMapper())

    return factory


class ServiceHandler(webapp.RequestHandler):
  """Web handler for RPC service.

  Overridden methods:
    get: All requests handled by 'handle' method.  HTTP method stored in
      attribute.  Takes remote_method parameter as derived from the URL mapping.
    post: All requests handled by 'handle' method.  HTTP method stored in
      attribute.  Takes remote_method parameter as derived from the URL mapping.
    redirect: Not implemented for this service handler.

  New methods:
    handle: Handle request for both GET and POST.

  Attributes (in addition to attributes in RequestHandler):
    service: Service instance associated with request being handled.
    method: Method of request.  Used by RPCMapper to determine match.
    remote_method: Sub-path as provided to the 'get' and 'post' methods.
  """

  def __init__(self, factory, service):
    """Constructor.

    Args:
      factory: Instance of ServiceFactory used for constructing new service
        instances used for handling requests.
      service: Service instance used for handling RPC.
    """
    self.__factory = factory
    self.__service = service

  @property
  def service(self):
    return self.__service

  def __show_info(self, service_path, remote_method):
    self.response.headers['content-type'] = 'text/plain; charset=utf-8'
    response_message = []
    if remote_method:
      response_message.append('%s.%s is a ProtoRPC method.\n\n' %(
        service_path, remote_method))
    else:
      response_message.append('%s is a ProtoRPC service.\n\n' % service_path)
    definition_name_function = getattr(self.__service, 'definition_name', None)
    if definition_name_function:
      definition_name = definition_name_function()
    else:
      definition_name = '%s.%s' % (self.__service.__module__,
                                   self.__service.__class__.__name__)

    response_message.append('Service %s\n\n' % definition_name)
    response_message.append('More about ProtoRPC: ')

    response_message.append('http://code.google.com/p/google-protorpc\n')
    self.response.out.write(util.pad_string(''.join(response_message)))

  def get(self, service_path, remote_method):
    """Handler method for GET requests.

    Args:
      service_path: Service path derived from request URL.
      remote_method: Sub-path after service path has been matched.
    """
    self.handle('GET', service_path, remote_method)

  def post(self, service_path, remote_method):
    """Handler method for POST requests.

    Args:
      service_path: Service path derived from request URL.
      remote_method: Sub-path after service path has been matched.
    """
    self.handle('POST', service_path, remote_method)

  def redirect(self, uri, permanent=False):
    """Not supported for services."""
    raise NotImplementedError('Services do not currently support redirection.')

  def __send_error(self,
                   http_code,
                   status_state,
                   error_message,
                   mapper,
                   error_name=None):
    status = remote.RpcStatus(state=status_state,
                              error_message=error_message,
                              error_name=error_name)
    mapper.build_response(self, status)
    self.response.headers['content-type'] = mapper.default_content_type

    logging.error(error_message)
    response_content = self.response.out.getvalue()
    padding = ' ' * max(0, 512 - len(response_content))
    self.response.out.write(padding)

    self.response.set_status(http_code, error_message)

  def __send_simple_error(self, code, message, pad=True):
    """Send error to caller without embedded message."""
    self.response.headers['content-type'] = 'text/plain; charset=utf-8'
    logging.error(message)
    self.response.set_status(code, message)

    response_message = six.moves.http_client.responses.get(code, 'Unknown Error')
    if pad:
      response_message = util.pad_string(response_message)
    self.response.out.write(response_message)

  def __get_content_type(self):
    content_type = self.request.headers.get('content-type', None)
    if not content_type:
      content_type = self.request.environ.get('HTTP_CONTENT_TYPE', None)
    if not content_type:
      return None

    # Lop off parameters from the end (for example content-encoding)
    return content_type.split(';', 1)[0].lower()

  def __headers(self, content_type):
    for name in self.request.headers:
      name = name.lower()
      if name == 'content-type':
        value = content_type
      elif name == 'content-length':
        value = str(len(self.request.body))
      else:
        value = self.request.headers.get(name, '')
      yield name, value

  def handle(self, http_method, service_path, remote_method):
    """Handle a service request.

    The handle method will handle either a GET or POST response.
    It is up to the individual mappers from the handler factory to determine
    which request methods they can service.

    If the protocol is not recognized, the request does not provide a correct
    request for that protocol or the service object does not support the
    requested RPC method, will return error code 400 in the response.

    Args:
      http_method: HTTP method of request.
      service_path: Service path derived from request URL.
      remote_method: Sub-path after service path has been matched.
    """
    self.response.headers['x-content-type-options'] = 'nosniff'
    if not remote_method and http_method == 'GET':
      # Special case a normal get request, presumably via a browser.
      self.error(405)
      self.__show_info(service_path, remote_method)
      return

    content_type = self.__get_content_type()

    # Provide server state to the service.  If the service object does not have
    # an "initialize_request_state" method, will not attempt to assign state.
    try:
      state_initializer = self.service.initialize_request_state
    except AttributeError:
      pass
    else:
      server_port = self.request.environ.get('SERVER_PORT', None)
      if server_port:
        server_port = int(server_port)

      request_state = remote.HttpRequestState(
          remote_host=self.request.environ.get('REMOTE_HOST', None),
          remote_address=self.request.environ.get('REMOTE_ADDR', None),
          server_host=self.request.environ.get('SERVER_HOST', None),
          server_port=server_port,
          http_method=http_method,
          service_path=service_path,
          headers=list(self.__headers(content_type)))
      state_initializer(request_state)

    if not content_type:
      self.__send_simple_error(400, 'Invalid RPC request: missing content-type')
      return

    # Search for mapper to mediate request.
    for mapper in self.__factory.all_request_mappers():
      if content_type in mapper.content_types:
        break
    else:
      if http_method == 'GET':
        self.error(six.moves.http_client.UNSUPPORTED_MEDIA_TYPE)
        self.__show_info(service_path, remote_method)
      else:
        self.__send_simple_error(six.moves.http_client.UNSUPPORTED_MEDIA_TYPE,
                                 'Unsupported content-type: %s' % content_type)
      return

    try:
      if http_method not in mapper.http_methods:
        if http_method == 'GET':
          self.error(six.moves.http_client.METHOD_NOT_ALLOWED)
          self.__show_info(service_path, remote_method)
        else:
          self.__send_simple_error(six.moves.http_client.METHOD_NOT_ALLOWED,
                                   'Unsupported HTTP method: %s' % http_method)
        return

      try:
        try:
          method = getattr(self.service, remote_method)
          method_info = method.remote
        except AttributeError as err:
          self.__send_error(
          400, remote.RpcState.METHOD_NOT_FOUND_ERROR,
            'Unrecognized RPC method: %s' % remote_method,
            mapper)
          return

        request = mapper.build_request(self, method_info.request_type)
      except (RequestError, messages.DecodeError) as err:
        self.__send_error(400,
                          remote.RpcState.REQUEST_ERROR,
                          'Error parsing ProtoRPC request (%s)' % err,
                          mapper)
        return

      try:
        response = method(request)
      except remote.ApplicationError as err:
        self.__send_error(400,
                          remote.RpcState.APPLICATION_ERROR,
                          err.message,
                          mapper,
                          err.error_name)
        return

      mapper.build_response(self, response)
    except Exception as err:
      logging.error('An unexpected error occured when handling RPC: %s',
                    err, exc_info=1)

      self.__send_error(500,
                        remote.RpcState.SERVER_ERROR,
                        'Internal Server Error',
                        mapper)
      return


# TODO(rafek): Support tag-id only forms.
class URLEncodedRPCMapper(RPCMapper):
  """Request mapper for application/x-www-form-urlencoded forms.

  This mapper is useful for building forms that can invoke RPC.  Many services
  are also configured to work using URL encoded request information because
  of its perceived ease of programming and debugging.

  The mapper must be provided with at least method_parameter or
  remote_method_pattern so that it is possible to determine how to determine the
  requests RPC method.  If both are provided, the service will respond to both
  method request types, however, only one may be present in a given request.
  If both types are detected, the request will not match.
  """

  def __init__(self, parameter_prefix=''):
    """Constructor.

    Args:
      parameter_prefix: If provided, all the parameters in the form are
        expected to begin with that prefix.
    """
    # Private attributes:
    #   __parameter_prefix: parameter prefix as provided by constructor
    #     parameter.
    super(URLEncodedRPCMapper, self).__init__(['POST'],
                                              _URLENCODED_CONTENT_TYPE,
                                              self)
    self.__parameter_prefix = parameter_prefix

  def encode_message(self, message):
    """Encode a message using parameter prefix.

    Args:
      message: Message to URL Encode.

    Returns:
      URL encoded message.
    """
    return protourlencode.encode_message(message,
                                         prefix=self.__parameter_prefix)

  @property
  def parameter_prefix(self):
    """Prefix all form parameters are expected to begin with."""
    return self.__parameter_prefix

  def build_request(self, handler, request_type):
    """Build request from URL encoded HTTP request.

    Constructs message from names of URL encoded parameters.  If this service
    handler has a parameter prefix, parameters must begin with it or are
    ignored.

    Args:
      handler: RequestHandler instance that is servicing request.
      request_type: Message type to build.

    Returns:
      Instance of request_type populated by protocol buffer in request
        parameters.

    Raises:
      RequestError if message type contains nested message field or repeated
      message field.  Will raise RequestError if there are any repeated
      parameters.
    """
    request = request_type()
    builder = protourlencode.URLEncodedRequestBuilder(
        request, prefix=self.__parameter_prefix)
    for argument in sorted(handler.request.arguments()):
      values = handler.request.get_all(argument)
      try:
        builder.add_parameter(argument, values)
      except messages.DecodeError as err:
        raise RequestError(str(err))
    return request


class ProtobufRPCMapper(RPCMapper):
  """Request mapper for application/x-protobuf service requests.

  This mapper will parse protocol buffer from a POST body and return the request
  as a protocol buffer.
  """

  def __init__(self):
    super(ProtobufRPCMapper, self).__init__(['POST'],
                                            _PROTOBUF_CONTENT_TYPE,
                                            protobuf)


class JSONRPCMapper(RPCMapper):
  """Request mapper for application/x-protobuf service requests.

  This mapper will parse protocol buffer from a POST body and return the request
  as a protocol buffer.
  """

  def __init__(self):
    super(JSONRPCMapper, self).__init__(
        ['POST'],
        _JSON_CONTENT_TYPE,
        protojson,
        content_types=_EXTRA_JSON_CONTENT_TYPES)


def service_mapping(services,
                    registry_path=DEFAULT_REGISTRY_PATH):
  """Create a services mapping for use with webapp.

  Creates basic default configuration and registration for ProtoRPC services.
  Each service listed in the service mapping has a standard service handler
  factory created for it.

  The list of mappings can either be an explicit path to service mapping or
  just services.  If mappings are just services, they will automatically
  be mapped to their default name.  For exampel:

    package = 'my_package'

    class MyService(remote.Service):
      ...

    server_mapping([('/my_path', MyService),  # Maps to /my_path
                    MyService,                # Maps to /my_package/MyService
                   ])

  Specifying a service mapping:

    Normally services are mapped to URL paths by specifying a tuple
    (path, service):
      path: The path the service resides on.
      service: The service class or service factory for creating new instances
        of the service.  For more information about service factories, please
        see remote.Service.new_factory.

    If no tuple is provided, and therefore no path specified, a default path
    is calculated by using the fully qualified service name using a URL path
    separator for each of its components instead of a '.'.

  Args:
    services: Can be service type, service factory or string definition name of
        service being mapped or list of tuples (path, service):
      path: Path on server to map service to.
      service: Service type, service factory or string definition name of
        service being mapped.
      Can also be a dict.  If so, the keys are treated as the path and values as
      the service.
    registry_path: Path to give to registry service.  Use None to disable
      registry service.

  Returns:
    List of tuples defining a mapping of request handlers compatible with a
    webapp application.

  Raises:
    ServiceConfigurationError when duplicate paths are provided.
  """
  if isinstance(services, dict):
    services = six.iteritems(services)
  mapping = []
  registry_map = {}

  if registry_path is not None:
    registry_service = registry.RegistryService.new_factory(registry_map)
    services = list(services) + [(registry_path, registry_service)]
    mapping.append((registry_path + r'/form(?:/)?',
                    forms.FormsHandler.new_factory(registry_path)))
    mapping.append((registry_path + r'/form/(.+)', forms.ResourceHandler))

  paths = set()
  for service_item in services:
    infer_path = not isinstance(service_item, (list, tuple))
    if infer_path:
      service = service_item
    else:
      service = service_item[1]

    service_class = getattr(service, 'service_class', service)

    if infer_path:
      path = '/' + service_class.definition_name().replace('.', '/')
    else:
      path = service_item[0]

    if path in paths:
      raise ServiceConfigurationError(
        'Path %r is already defined in service mapping' % path.encode('utf-8'))
    else:
      paths.add(path)

    # Create service mapping for webapp.
    new_mapping = ServiceHandlerFactory.default(service).mapping(path)
    mapping.append(new_mapping)

    # Update registry with service class.
    registry_map[path] = service_class

  return mapping


def run_services(services,
                 registry_path=DEFAULT_REGISTRY_PATH):
  """Handle CGI request using service mapping.

  Args:
    Same as service_mapping.
  """
  mappings = service_mapping(services, registry_path=registry_path)
  application = webapp.WSGIApplication(mappings)
  webapp_util.run_wsgi_app(application)