:mod:`grpcserver` --- SR OS gRPC server
=======================================

.. module:: grpcserver
   :synopsis: SR OS gRPC server integration.  

.. note:: This module is available when executing on SR OS only. On a remote
          machine, the gRPC server and it's functionality are not supported.

The :mod:`grpcserver` module allows a Python 3 application to act as a handler for gRPC calls providing
functionality to handle gRPC calls within a Python application running on SR OS and issue responses through 
the SR OS gRPC server.

.. note:: In order to use this module, the Python application must be configured as a ``python-script`` within
          the SR OS configuration and referenced from the gRPC server configuration.

To use this library to handle gRPC packages, services and RPCs the workflow is:

1. Define a handler function for each RPC in the gRPC package/service proto file.  This function will perform
   the activities that should happen when the RPC is called
2. Add the handler function to the gRPC server library.  This is the glue between the package/service/RPC and the Python
   application code
3. Use the :func:`handle_rpc` function to ready the Python interpreter and gRPC server to handle the RPC


Classes
-------

.. class:: Context

    gRPC context object passed to each handler function.

    .. attribute:: rpc

        Name of the RPC called, including the gRPC package and service.

    .. method:: abort(code, details=None)

        Sets the status code and details message to be returned to the gRPC client.

        :param code: Status code to set (defined in :class:`StatusCode`)
        :type code: int
        :param details: Message provided.  This is derived from the code when omitted
        :type details: str, optional
        :raises AbortError: Terminate the handler function
                        
.. Class:: StatusCode

    Available gRPC status codes.

    .. attribute:: OK = 0
    .. attribute:: CANCELLED = 1
    .. attribute:: UNKNOWN = 2
    .. attribute:: INVALID_ARGUMENT = 3
    .. attribute:: DEADLINE_EXCEEDED = 4
    .. attribute:: NOT_FOUND = 5
    .. attribute:: ALREADY_EXISTS = 6
    .. attribute:: PERMISSION_DENIED = 7
    .. attribute:: RESOURCE_EXHAUSTED = 8
    .. attribute:: FAILED_PRECONDITION = 9
    .. attribute:: ABORTED = 10
    .. attribute:: OUT_OF_RANGE = 11
    .. attribute:: UNIMPLEMENTED = 12
    .. attribute:: INTERNAL = 13
    .. attribute:: UNAVAILABLE = 14
    .. attribute:: DATA_LOSS = 15
    .. attribute:: UNAUTHENTICATED = 16

Functions
---------

.. function:: add_handler(service, rpc, handler, *, package=None)

    Adds a handler function for the specified Package/Service/RPC.

    :param package: gRPC package name
    :type package: str, optional
    :param service: gRPC service name
    :type service: str
    :param rpc: RPC name
    :type rpc: str
    :param handler: Handler function name

.. function:: handle_rpc()

    Handle any incoming configured Packages/Services/RPCs.  

    The response(s) generated by the handler function will be sent to the gRPC client.
    This function does not return any data.  It will either complete successfully or raise an exception.

    .. note:: This function should only be called once all handlers have been added using the :func:`add_handler` function.

    :raises RpcError: When an error occurs during handling of the RPC
    :raises NotImplementedError: When no handler is found for the current RPC

Exceptions
----------

If a handler function returns a response that does not conform to the expected message format, an error will occur when the library 
attempts to serialize and send the response to the gRPC client.  In this case, a :class:`ValueError` or :class:`TypeError` will be raised.

When an exception occurs in the handler function, the library will catch this exception and send an error reponse to the gRPC client with the StatusCode ``INTERNAL``.
The exception is than allowed to propagate and can either be caught by the script or will result in termination of the script.

.. exception:: RpcError(Exception)

    Exception raised when an error occurs during the handling of an RPC.
    For example, the connection closed while reading a request or sending a response.