google/appengine/api/channel/channel.py

#!/usr/bin/env python
#
# Copyright 2007 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.
#




"""Channel API.

This module allows App Engine apps to push messages to a client.

Functions defined in this module:
  create_channel: Creates a channel to send messages to.
  send_message: Send a message to any clients listening on the given channel.
"""







import os

from google.appengine.api import api_base_pb
from google.appengine.api import apiproxy_stub_map
from google.appengine.api.channel import channel_service_pb
from google.appengine.runtime import apiproxy_errors








MAXIMUM_CLIENT_ID_LENGTH = 256


MAXIMUM_TOKEN_DURATION_MINUTES = 24 * 60






MAXIMUM_MESSAGE_LENGTH = 32767


class Error(Exception):
  """Base error class for this module."""


class InvalidChannelClientIdError(Error):
  """Error that indicates a bad client id."""


class InvalidChannelTokenDurationError(Error):
  """Error that indicates the requested duration is invalid."""


class InvalidMessageError(Error):
  """Error that indicates a message is malformed."""


class AppIdAliasRequired(Error):
  """Error that indicates you must assign an application alias to your app."""


def _ToChannelError(error):
  """Translate an application error to a channel Error, if possible.

  Args:
    error: An ApplicationError to translate.

  Returns:
    The appropriate channel service error, if a match is found, or the original
    ApplicationError.
  """
  error_map = {
      channel_service_pb.ChannelServiceError.INVALID_CHANNEL_KEY:
        InvalidChannelClientIdError,
      channel_service_pb.ChannelServiceError.BAD_MESSAGE:
        InvalidMessageError,
      channel_service_pb.ChannelServiceError.APPID_ALIAS_REQUIRED:
        AppIdAliasRequired
      }

  if error.application_error in error_map:
    return error_map[error.application_error](error.error_detail)
  else:
    return error


def _GetService():
  """Gets the service name to use, based on if we're on the dev server."""
  server_software = os.environ.get('SERVER_SOFTWARE', '')
  if (server_software.startswith('Devel') or
      server_software.startswith('test')):


    return 'channel'
  else:
    return 'xmpp'


def _ValidateClientId(client_id):
  """Validates a client id.

  Args:
    client_id: The client id provided by the application.

  Returns:
    If the client id is of type str, returns the original client id.
    If the client id is of type unicode, returns the id encoded to utf-8.

  Raises:
    InvalidChannelClientIdError: if client id is not an instance of str or
        unicode, or if the (utf-8 encoded) string is longer than 64 characters.
  """
  if not isinstance(client_id, basestring):
    raise InvalidChannelClientIdError('"%s" is not a string.' % client_id)

  if isinstance(client_id, unicode):
    client_id = client_id.encode('utf-8')


  if len(client_id) > MAXIMUM_CLIENT_ID_LENGTH:
    msg = 'Client id length %d is greater than max length %d' % (
         len(client_id), MAXIMUM_CLIENT_ID_LENGTH)
    raise InvalidChannelClientIdError(msg)

  return client_id



def create_channel(client_id, duration_minutes=None):
  """Create a channel.

  Args:
    client_id: A string to identify this channel on the server side.
    duration_minutes: An int specifying the number of minutes for which the
        returned token should be valid.

  Returns:
    A token that the client can use to connect to the channel.

  Raises:
    InvalidChannelClientIdError: if clientid is not an instance of str or
        unicode, or if the (utf-8 encoded) string is longer than 64 characters.
    InvalidChannelTokenDurationError: if duration_minutes is not a number, less
        than 1, or greater than 1440 (the number of minutes in a day).
    Other errors returned by _ToChannelError
  """


  client_id = _ValidateClientId(client_id)

  if not duration_minutes is None:
    if not isinstance(duration_minutes, (int, long)):
      raise InvalidChannelTokenDurationError(
         'Argument duration_minutes must be integral')
    elif duration_minutes < 1:
      raise InvalidChannelTokenDurationError(
         'Argument duration_minutes must not be less than 1')
    elif duration_minutes > MAXIMUM_TOKEN_DURATION_MINUTES:
      msg = ('Argument duration_minutes must be less than %d'
             % (MAXIMUM_TOKEN_DURATION_MINUTES + 1))
      raise InvalidChannelTokenDurationError(msg)


  request = channel_service_pb.CreateChannelRequest()
  response = channel_service_pb.CreateChannelResponse()

  request.set_application_key(client_id)
  if not duration_minutes is None:
    request.set_duration_minutes(duration_minutes)

  try:
    apiproxy_stub_map.MakeSyncCall(_GetService(),
                                   'CreateChannel',
                                   request,
                                   response)
  except apiproxy_errors.ApplicationError, e:
    raise _ToChannelError(e)

  return response.token()



def send_message(client_id, message):
  """Send a message to a channel.

  Args:
    client_id: The client id passed to create_channel.
    message: A string representing the message to send.

  Raises:
    InvalidChannelClientIdError: if client_id is not an instance of str or
        unicode, or if the (utf-8 encoded) string is longer than 64 characters.
    InvalidMessageError: if the message isn't a string or is too long.
    Errors returned by _ToChannelError
  """

  client_id = _ValidateClientId(client_id)

  if isinstance(message, unicode):
    message = message.encode('utf-8')
  elif not isinstance(message, str):
    raise InvalidMessageError('Message must be a string')

  if len(message) > MAXIMUM_MESSAGE_LENGTH:
    raise InvalidMessageError(
        'Message must be no longer than %d chars' % MAXIMUM_MESSAGE_LENGTH)

  request = channel_service_pb.SendMessageRequest()
  response = api_base_pb.VoidProto()

  request.set_application_key(client_id)
  request.set_message(message)

  try:
    apiproxy_stub_map.MakeSyncCall(_GetService(),
                                   'SendChannelMessage',
                                   request,
                                   response)
  except apiproxy_errors.ApplicationError, e:
    raise _ToChannelError(e)