src/python/grpcio/grpc/framework/alpha/interfaces.py

# Copyright 2015-2016, Google Inc.
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are
# met:
#
#     * Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
#     * Redistributions in binary form must reproduce the above
# copyright notice, this list of conditions and the following disclaimer
# in the documentation and/or other materials provided with the
# distribution.
#     * Neither the name of Google Inc. nor the names of its
# contributors may be used to endorse or promote products derived from
# this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

"""Interfaces of GRPC."""

import abc
import enum

import six

# exceptions is referenced from specification in this module.
from grpc.framework.alpha import exceptions  # pylint: disable=unused-import
from grpc.framework.foundation import activated
from grpc.framework.foundation import future


@enum.unique
class Cardinality(enum.Enum):
  """Constants for the four cardinalities of RPC."""

  UNARY_UNARY = 'request-unary/response-unary'
  UNARY_STREAM = 'request-unary/response-streaming'
  STREAM_UNARY = 'request-streaming/response-unary'
  STREAM_STREAM = 'request-streaming/response-streaming'


@enum.unique
class Abortion(enum.Enum):
  """Categories of RPC abortion."""

  CANCELLED = 'cancelled'
  EXPIRED = 'expired'
  NETWORK_FAILURE = 'network failure'
  SERVICED_FAILURE = 'serviced failure'
  SERVICER_FAILURE = 'servicer failure'


class CancellableIterator(six.with_metaclass(abc.ABCMeta)):
  """Implements the Iterator protocol and affords a cancel method."""

  @abc.abstractmethod
  def __iter__(self):
    """Returns the self object in accordance with the Iterator protocol."""
    raise NotImplementedError()

  def __next__(self):
    return self.next()

  @abc.abstractmethod
  def next(self):
    """Returns a value or raises StopIteration per the Iterator protocol."""
    raise NotImplementedError()

  @abc.abstractmethod
  def cancel(self):
    """Requests cancellation of whatever computation underlies this iterator."""
    raise NotImplementedError()


class RpcContext(six.with_metaclass(abc.ABCMeta)):
  """Provides RPC-related information and action."""

  @abc.abstractmethod
  def is_active(self):
    """Describes whether the RPC is active or has terminated."""
    raise NotImplementedError()

  @abc.abstractmethod
  def time_remaining(self):
    """Describes the length of allowed time remaining for the RPC.
    Returns:
      A nonnegative float indicating the length of allowed time in seconds
      remaining for the RPC to complete before it is considered to have timed
      out.
    """
    raise NotImplementedError()

  @abc.abstractmethod
  def add_abortion_callback(self, abortion_callback):
    """Registers a callback to be called if the RPC is aborted.
    Args:
      abortion_callback: A callable to be called and passed an Abortion value
        in the event of RPC abortion.
    """
    raise NotImplementedError()


class UnaryUnarySyncAsync(six.with_metaclass(abc.ABCMeta)):
  """Affords invoking a unary-unary RPC synchronously or asynchronously.
  Values implementing this interface are directly callable and present an
  "async" method. Both calls take a request value and a numeric timeout.
  Direct invocation of a value of this type invokes its associated RPC and
  blocks until the RPC's response is available. Calling the "async" method
  of a value of this type invokes its associated RPC and immediately returns a
  future.Future bound to the asynchronous execution of the RPC.
  """

  @abc.abstractmethod
  def __call__(self, request, timeout):
    """Synchronously invokes the underlying RPC.
    Args:
      request: The request value for the RPC.
      timeout: A duration of time in seconds to allow for the RPC.
    Returns:
      The response value for the RPC.
    Raises:
      exceptions.RpcError: Indicating that the RPC was aborted.
    """
    raise NotImplementedError()

  @abc.abstractmethod
  def async(self, request, timeout):
    """Asynchronously invokes the underlying RPC.
    Args:
      request: The request value for the RPC.
      timeout: A duration of time in seconds to allow for the RPC.
    Returns:
      A future.Future representing the RPC. In the event of RPC completion, the
        returned Future's result value will be the response value of the RPC.
        In the event of RPC abortion, the returned Future's exception value
        will be an exceptions.RpcError.
    """
    raise NotImplementedError()


class StreamUnarySyncAsync(six.with_metaclass(abc.ABCMeta)):
  """Affords invoking a stream-unary RPC synchronously or asynchronously.
  Values implementing this interface are directly callable and present an
  "async" method. Both calls take an iterator of request values and a numeric
  timeout. Direct invocation of a value of this type invokes its associated RPC
  and blocks until the RPC's response is available. Calling the "async" method
  of a value of this type invokes its associated RPC and immediately returns a
  future.Future bound to the asynchronous execution of the RPC.
  """

  @abc.abstractmethod
  def __call__(self, request_iterator, timeout):
    """Synchronously invokes the underlying RPC.

    Args:
      request_iterator: An iterator that yields request values for the RPC.
      timeout: A duration of time in seconds to allow for the RPC.

    Returns:
      The response value for the RPC.

    Raises:
      exceptions.RpcError: Indicating that the RPC was aborted.
    """
    raise NotImplementedError()

  @abc.abstractmethod
  def async(self, request_iterator, timeout):
    """Asynchronously invokes the underlying RPC.

    Args:
      request_iterator: An iterator that yields request values for the RPC.
      timeout: A duration of time in seconds to allow for the RPC.

    Returns:
      A future.Future representing the RPC. In the event of RPC completion, the
        returned Future's result value will be the response value of the RPC.
        In the event of RPC abortion, the returned Future's exception value
        will be an exceptions.RpcError.
    """
    raise NotImplementedError()


class RpcMethodDescription(six.with_metaclass(abc.ABCMeta)):
  """A type for the common aspects of RPC method descriptions."""

  @abc.abstractmethod
  def cardinality(self):
    """Identifies the cardinality of this RpcMethodDescription.

    Returns:
      A Cardinality value identifying whether or not this
        RpcMethodDescription is request-unary or request-streaming and
        whether or not it is response-unary or response-streaming.
    """
    raise NotImplementedError()


class RpcMethodInvocationDescription(six.with_metaclass(abc.ABCMeta, RpcMethodDescription)):
  """Invocation-side description of an RPC method."""

  @abc.abstractmethod
  def serialize_request(self, request):
    """Serializes a request value.

    Args:
      request: A request value appropriate for the RPC method described by this
        RpcMethodInvocationDescription.

    Returns:
      The serialization of the given request value as a
        bytestring.
    """
    raise NotImplementedError()

  @abc.abstractmethod
  def deserialize_response(self, serialized_response):
    """Deserializes a response value.

    Args:
      serialized_response: A bytestring that is the serialization of a response
        value appropriate for the RPC method described by this
        RpcMethodInvocationDescription.

    Returns:
      A response value corresponding to the given bytestring.
    """
    raise NotImplementedError()


class RpcMethodServiceDescription(six.with_metaclass(abc.ABCMeta, RpcMethodDescription)):
  """Service-side description of an RPC method."""

  @abc.abstractmethod
  def deserialize_request(self, serialized_request):
    """Deserializes a request value.

    Args:
      serialized_request: A bytestring that is the serialization of a request
        value appropriate for the RPC method described by this
        RpcMethodServiceDescription.

    Returns:
      A request value corresponding to the given bytestring.
    """
    raise NotImplementedError()

  @abc.abstractmethod
  def serialize_response(self, response):
    """Serializes a response value.

    Args:
      response: A response value appropriate for the RPC method described by
        this RpcMethodServiceDescription.

    Returns:
      The serialization of the given response value as a
        bytestring.
    """
    raise NotImplementedError()

  @abc.abstractmethod
  def service_unary_unary(self, request, context):
    """Carries out this RPC.

    This method may only be called if the cardinality of this
    RpcMethodServiceDescription is Cardinality.UNARY_UNARY.

    Args:
      request: A request value appropriate for the RPC method described by this
        RpcMethodServiceDescription.
      context: An RpcContext object for the RPC.

    Returns:
      A response value appropriate for the RPC method described by this
        RpcMethodServiceDescription.
    """
    raise NotImplementedError()

  @abc.abstractmethod
  def service_unary_stream(self, request, context):
    """Carries out this RPC.

    This method may only be called if the cardinality of this
    RpcMethodServiceDescription is Cardinality.UNARY_STREAM.

    Args:
      request: A request value appropriate for the RPC method described by this
        RpcMethodServiceDescription.
      context: An RpcContext object for the RPC.

    Yields:
      Zero or more response values appropriate for the RPC method described by
        this RpcMethodServiceDescription.
    """
    raise NotImplementedError()

  @abc.abstractmethod
  def service_stream_unary(self, request_iterator, context):
    """Carries out this RPC.

    This method may only be called if the cardinality of this
    RpcMethodServiceDescription is Cardinality.STREAM_UNARY.

    Args:
      request_iterator: An iterator of request values appropriate for the RPC
        method described by this RpcMethodServiceDescription.
      context: An RpcContext object for the RPC.

    Returns:
      A response value appropriate for the RPC method described by this
        RpcMethodServiceDescription.
    """
    raise NotImplementedError()

  @abc.abstractmethod
  def service_stream_stream(self, request_iterator, context):
    """Carries out this RPC.

    This method may only be called if the cardinality of this
    RpcMethodServiceDescription is Cardinality.STREAM_STREAM.

    Args:
      request_iterator: An iterator of request values appropriate for the RPC
        method described by this RpcMethodServiceDescription.
      context: An RpcContext object for the RPC.

    Yields:
      Zero or more response values appropriate for the RPC method described by
        this RpcMethodServiceDescription.
    """
    raise NotImplementedError()


class Stub(six.with_metaclass(abc.ABCMeta)):
  """A stub with callable RPC method names for attributes.

  Instances of this type are context managers and only afford RPC invocation
  when used in context.

  Instances of this type, when used in context, respond to attribute access
  as follows: if the requested attribute is the name of a unary-unary RPC
  method, the value of the attribute will be a UnaryUnarySyncAsync with which
  to invoke the RPC method. If the requested attribute is the name of a
  unary-stream RPC method, the value of the attribute will be a callable taking
  a request object and a timeout parameter and returning a CancellableIterator
  that yields the response values of the RPC. If the requested attribute is the
  name of a stream-unary RPC method, the value of the attribute will be a
  StreamUnarySyncAsync with which to invoke the RPC method. If the requested
  attribute is the name of a stream-stream RPC method, the value of the
  attribute will be a callable taking an iterator of request objects and a
  timeout and returning a CancellableIterator that yields the response values
  of the RPC.

  In all cases indication of abortion is indicated by raising of
  exceptions.RpcError, exceptions.CancellationError,
  and exceptions.ExpirationError.
  """


class Server(six.with_metaclass(abc.ABCMeta, activated.Activated)):
  """A GRPC Server."""

  @abc.abstractmethod
  def port(self):
    """Reports the port on which the server is serving.

    This method may only be called while the server is activated.

    Returns:
      The port on which the server is serving.
    """
    raise NotImplementedError()