=================
JSON-RPC Protocol
=================

berryMQ uses JSON-RPC as a communication protocol.
:class:`berrymq.connect.ExportedFunctions` class implements JSON-RPC interface.

Terms
=====

``addr``
   This is a tuple of URL and port number.
   
``ttl``
   Time to Live. Unit is "second". 
   If nodes don't communicate longer than this term, line will be disconnected.

``token``
   This identifies connections. In python this is generated by ``str(uuid.uuid1())``.

``client``
   This is a node which calls "connection" procedures.
   
``server``
   This is a node which is called "connection" procedures from client.


.. currentmodule:: berrymq.connect

JSON-RPC functions
==================

.. class:: ExportedFunctions

   .. method:: interconnect(addr, token, ttl)

      Connect to other node equality. 
      This is :ref:`inter-process style01 <inter_process_style01>`.

      You should generate ``token`` at client side and pass to server.
      Once you call this function, this node will callback to ``addr``.

      :return: token
      :rtype: str

   .. method:: connect_oneway(ttl)

      Connect to other node. Target node won't call back to client.
      This is :ref:`inter-process style02 <inter_process_style02>`.

      :return: token
      :rtype: str

   .. method:: connect_via_queue(identifier, ttl)

      Connect to other node with queue. 
      This is :ref:`inter-process style03 <inter_process_style03>`.

      :param identifier: receive filter. see :ref:`identifier`
      :type  identifier: str
      :return: token
      :rtype: str

   .. method:: send_message(token, identifier, args, kwargs)

      It's key function for inter-process communication.

      :param token: return value of connection methods
      :type  token: str
      :param identifier: message identifier
      :type  identifier: str
      :param args: message args
      :type  args: list
      :param kwargs: message keyword args
      :type  kwargs: dict

      :return: status code
      :rtype: "ok" or "invalid token" or "timeout"

   .. method:: get(token, block, timeout):
   
      Get message from queue. 
      This function is available if you connect by :meth:`connect_via_queue`.

      .. seealso:: :meth:`berrymq.Queue.get`

      :return: message object or error code
      :rtype:  {id, args, kwargs} or "invalid token" or "timeout"

   .. method:: get_nowait(token)

      .. seealso:: :meth:`berrymq.Queue.get_nowait`

      :return: message object or error code
      :rtype:  {id, args, kwargs} or "invalid token" or "timeout"

   .. method:: close_connection(token)

      close session.

      :param token: return value of connection methods
      :type  token: str