docs/source/development/messaging.txt

======================
 Messaging in IPython
======================


Introduction
============

This document explains the basic communications design and messaging
specification for how the various IPython objects interact over a network
transport.  The current implementation uses the ZeroMQ_ library for messaging
within and between hosts.

.. Note::

   This document should be considered the authoritative description of the
   IPython messaging protocol, and all developers are strongly encouraged to
   keep it updated as the implementation evolves, so that we have a single
   common reference for all protocol details.
   
The basic design is explained in the following diagram:

.. image:: frontend-kernel.png
   :width: 450px
   :alt: IPython kernel/frontend messaging architecture.
   :align: center
   :target: ../_images/frontend-kernel.png

A single kernel can be simultaneously connected to one or more frontends.  The
kernel has three sockets that serve the following functions:

1. REQ: this socket is connected to a *single* frontend at a time, and it allows
   the kernel to request input from a frontend when :func:`raw_input` is called.
   The frontend holding the matching REP socket acts as a 'virtual keyboard'
   for the kernel while this communication is happening (illustrated in the
   figure by the black outline around the central keyboard).  In practice,
   frontends may display such kernel requests using a special input widget or
   otherwise indicating that the user is to type input for the kernel instead
   of normal commands in the frontend.

2. XREP: this single sockets allows multiple incoming connections from
   frontends, and this is the socket where requests for code execution, object
   information, prompts, etc. are made to the kernel by any frontend.  The
   communication on this socket is a sequence of request/reply actions from
   each frontend and the kernel.

3. PUB: this socket is the 'broadcast channel' where the kernel publishes all
   side effects (stdout, stderr, etc.) as well as the requests coming from any
   client over the XREP socket and its own requests on the REP socket.  There
   are a number of actions in Python which generate side effects: :func:`print`
   writes to ``sys.stdout``, errors generate tracebacks, etc.  Additionally, in
   a multi-client scenario, we want all frontends to be able to know what each
   other has sent to the kernel (this can be useful in collaborative scenarios,
   for example).  This socket allows both side effects and the information
   about communications taking place with one client over the XREQ/XREP channel
   to be made available to all clients in a uniform manner.

   All messages are tagged with enough information (details below) for clients
   to know which messages come from their own interaction with the kernel and
   which ones are from other clients, so they can display each type
   appropriately.

The actual format of the messages allowed on each of these channels is
specified below.  Messages are dicts of dicts with string keys and values that
are reasonably representable in JSON.  Our current implementation uses JSON
explicitly as its message format, but this shouldn't be considered a permanent
feature.  As we've discovered that JSON has non-trivial performance issues due
to excessive copying, we may in the future move to a pure pickle-based raw
message format.  However, it should be possible to easily convert from the raw
objects to JSON, since we may have non-python clients (e.g. a web frontend).
As long as it's easy to make a JSON version of the objects that is a faithful
representation of all the data, we can communicate with such clients.

.. Note::

   Not all of these have yet been fully fleshed out, but the key ones are, see
   kernel and frontend files for actual implementation details.

   
Python functional API
=====================

As messages are dicts, they map naturally to a ``func(**kw)`` call form.  We
should develop, at a few key points, functional forms of all the requests that
take arguments in this manner and automatically construct the necessary dict
for sending.


General Message Format
======================

All messages send or received by any IPython process should have the following
generic structure::
    
    {
      # The message header contains a pair of unique identifiers for the
      # originating session and the actual message id, in addition to the
      # username for the process that generated the message.  This is useful in
      # collaborative settings where multiple users may be interacting with the
      # same kernel simultaneously, so that frontends can label the various
      # messages in a meaningful way.
      'header' : { 'msg_id' : uuid,
                   'username' : str,
		   'session' : uuid
		 },

      # In a chain of messages, the header from the parent is copied so that
      # clients can track where messages come from.
      'parent_header' : dict,

      # All recognized message type strings are listed below.
      'msg_type' : str,

      # The actual content of the message must be a dict, whose structure
      # depends on the message type.x
      'content' : dict,
    }

For each message type, the actual content will differ and all existing message
types are specified in what follows of this document.


Messages on the XREP/XREQ socket
================================

.. _execute:

Execute
-------

The execution request contains a single string, but this may be a multiline
string.  The kernel is responsible for splitting this into possibly more than
one block and deciding whether to compile these in 'single' or 'exec' mode.
We're still sorting out this policy.  The current inputsplitter is capable of
splitting the input for blocks that can all be run as 'single', but in the long
run it may prove cleaner to only use 'single' mode for truly single-line
inputs, and run all multiline input in 'exec' mode.  This would preserve the
natural behavior of single-line inputs while allowing long cells to behave more
likea a script.  This design will be refined as we complete the implementation.

Message type: ``execute_request``::

    content = {
        # Source code to be executed by the kernel, one or more lines.
	'code' : str,

	# A boolean flag which, if True, signals the kernel to execute this
	# code as quietly as possible.  This means that the kernel will compile
	# the code with 'exec' instead of 'single' (so sys.displayhook will not
	# fire), and will *not*:
	#   - broadcast exceptions on the PUB socket
	#   - do any logging
	#   - populate any history
	# The default is False.
	'silent' : bool,
    }

Upon execution, the kernel *always* sends a reply, with a status code
indicating what happened and additional data depending on the outcome.

Message type: ``execute_reply``::

    content = {
      # One of: 'ok' OR 'error' OR 'abort'
      'status' : str,

      # Any additional data depends on status value
    }

When status is 'ok', the following extra fields are present::

    {
      # This has the same structure as the output of a prompt request, but is
      # for the client to set up the *next* prompt (with identical limitations
      # to a prompt request)
      'next_prompt' : {
            'prompt_string' : str,
	    'prompt_number' : int,
	    },
	    
      # The prompt number of the actual execution for this code, which may be
      # different from the one used when the code was typed, which was the
      # 'next_prompt' field of the *previous* request.  They will differ in the
      # case where there is more than one client talking simultaneously to a
      # kernel, since the numbers can go out of sync.  GUI clients can use this
      # to correct the previously written number in-place, terminal ones may
      # re-print a corrected one if desired.
      'prompt_number' : int,

      # The kernel will often transform the input provided to it.  This
      # contains the transformed code, which is what was actually executed.
      'transformed_code' : str,

      # The execution payload is a dict with string keys that may have been
      # produced by the code being executed.  It is retrieved by the kernel at
      # the end of the execution and sent back to the front end, which can take
      # action on it as needed.  See main text for further details.
      'payload' : dict,
    }

.. admonition:: Execution payloads
    
   The notion of an 'execution payload' is different from a return value of a
   given set of code, which normally is just displayed on the pyout stream
   through the PUB socket.  The idea of a payload is to allow special types of
   code, typically magics, to populate a data container in the IPython kernel
   that will be shipped back to the caller via this channel.  The kernel will
   have an API for this, probably something along the lines of::

       ip.exec_payload_add(key, value)

   though this API is still in the design stages.  The data returned in this
   payload will allow frontends to present special views of what just happened.

   
When status is 'error', the following extra fields are present::

    {
      'exc_name' : str,   # Exception name, as a string
      'exc_value' : str,  # Exception value, as a string

      # The traceback will contain a list of frames, represented each as a
      # string.  For now we'll stick to the existing design of ultraTB, which
      # controls exception level of detail statefully.  But eventually we'll
      # want to grow into a model where more information is collected and
      # packed into the traceback object, with clients deciding how little or
      # how much of it to unpack.  But for now, let's start with a simple list
      # of strings, since that requires only minimal changes to ultratb as
      # written.
      'traceback' : list,
    }


When status is 'abort', there are for now no additional data fields.  This
happens when the kernel was interrupted by a signal.


Prompt
------

A simple request for a current prompt string.

Message type: ``prompt_request``::

    content = {}

In the reply, the prompt string comes back with the prompt number placeholder
*unevaluated*.  The message format is:
    
Message type: ``prompt_reply``::

    content = {
      'prompt_string' : str,
      'prompt_number' : int,
    }

Clients can produce a prompt with ``prompt_string.format(prompt_number)``, but
they should be aware that the actual prompt number for that input could change
later, in the case where multiple clients are interacting with a single
kernel. 


Object information
------------------

One of IPython's most used capabilities is the introspection of Python objects
in the user's namespace, typically invoked via the ``?`` and ``??`` characters
(which in reality are shorthands for the ``%pinfo`` magic).  This is used often
enough that it warrants an explicit message type, especially because frontends
may want to get object information in response to user keystrokes (like Tab or
F1) besides from the user explicitly typing code like ``x??``.

Message type: ``object_info_request``::

    content = {
        # The (possibly dotted) name of the object to be searched in all
	# relevant namespaces
	'name' : str,

	# The level of detail desired.  The default (0) is equivalent to typing
	# 'x?' at the prompt, 1 is equivalent to 'x??'.
	'detail_level' : int,
    }

The returned information will be a dictionary with keys very similar to the
field names that IPython prints at the terminal.
    
Message type: ``object_info_reply``::

    content = {
        # Flags for magics and system aliases
	'ismagic' : bool,
	'isalias' : bool,

	# The name of the namespace where the object was found ('builtin',
	# 'magics', 'alias', 'interactive', etc.)
	'namespace' : str,

	# The type name will be type.__name__ for normal Python objects, but it
	# can also be a string like 'Magic function' or 'System alias'
	'type_name' : str,

	'string_form' : str,

	# For objects with a __class__ attribute this will be set
	'base_class' : str,

	# For objects with a __len__ attribute this will be set
	'length' : int,

	# If the object is a function, class or method whose file we can find,
	# we give its full path
	'file' : str,

	# For pure Python callable objects, we can reconstruct the object
	# definition line which provides its call signature
	'definition' : str,

	# For instances, provide the constructor signature (the definition of
	# the __init__ method):
	'init_definition' : str,
	
	# Docstrings: for any object (function, method, module, package) with a
	# docstring, we show it.  But in addition, we may provide additional
	# docstrings.  For example, for instances we will show the constructor
	# and class docstrings as well, if available.
	'docstring' : str,

	# For instances, provide the constructor and class docstrings
	'init_docstring' : str,
	'class_docstring' : str,

	# If detail_level was 1, we also try to find the source code that
	# defines the object, if possible.  The string 'None' will indicate
	# that no source was found.
	'source' : str,
    }

    
Complete
--------

Message type: ``complete_request``::

    content = {
        # The text to be completed, such as 'a.is'
	'text' : str,

	# The full line, such as 'print a.is'.  This allows completers to
	# make decisions that may require information about more than just the
	# current word.
	'line' : str,
    }

Message type: ``complete_reply``::

    content = {
        # The list of all matches to the completion request, such as
	# ['a.isalnum', 'a.isalpha'] for the above example.
	'matches' : list
    }

    
History
-------

For clients to explicitly request history from a kernel.  The kernel has all
the actual execution history stored in a single location, so clients can
request it from the kernel when needed.

Message type: ``history_request``::

    content = {
    
      # If true, also return output history in the resulting dict.
      'output' : bool,

      # This parameter can be one of: A number,  a pair of numbers, 'all'
      # If not given, last 40 are returned.
      #  - number n: return the last n entries.
      #  - pair n1, n2: return entries in the range(n1, n2).
      #  - 'all': return all history
      'range' : n or (n1, n2) or 'all',

      # If a filter is given, it is  treated as a regular expression and only
      #  matching entries are returned.  re.search() is used to find matches.
      'filter' : str,
    }

Message type: ``history_reply``::

    content = {
      # A list of (number, input) pairs
      'input' : list,
      
      # A list of (number, output) pairs
      'output' : list,
      }

    
Messages on the PUB/SUB socket
==============================

Streams (stdout,  stderr, etc)
------------------------------

Message type: ``stream``::

    content = {
        # The name of the stream is one of 'stdin', 'stdout', 'stderr'
	'name' : str,
	
	# The data is an arbitrary string to be written to that stream
	'data' : str,
    }

When a kernel receives a raw_input call, it should also broadcast it on the pub
socket with the names 'stdin' and 'stdin_reply'.  This will allow other clients
to monitor/display kernel interactions and possibly replay them to their user
or otherwise expose them.

Python inputs
-------------

These messages are the re-broadcast of the ``execute_request``.

Message type: ``pyin``::

    content = {
        # Source code to be executed, one or more lines
	'code' : str
    }

Python outputs
--------------

When Python produces output from code that has been compiled in with the
'single' flag to :func:`compile`, any expression that produces a value (such as
``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
this value whatever it wants.  The default behavior of ``sys.displayhook`` in
the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
the value as long as it is not ``None`` (which isn't printed at all).  In our
case, the kernel instantiates as ``sys.displayhook`` an object which has
similar behavior, but which instead of printing to stdout, broadcasts these
values as ``pyout`` messages for clients to display appropriately.

Message type: ``pyout``::

    content = {
        # The data is typically the repr() of the object.
	'data' : str,
	
	# The prompt number for this execution is also provided so that clients
	# can display it, since IPython automatically creates variables called
	# _N (for prompt N).
	'prompt_number' : int,
    }
    
Python errors
-------------

When an error occurs during code execution

Message type: ``pyerr``::

    content = {
       # Similar content to the execute_reply messages for the 'error' case,
       # except the 'status' field is omitted.
    }

Kernel crashes
--------------

When the kernel has an unexpected exception, caught by the last-resort
sys.excepthook, we should broadcast the crash handler's output before exiting.
This will allow clients to notice that a kernel died, inform the user and
propose further actions.

Message type: ``crash``::

    content = {
       # Similarly to the 'error' case for execute_reply messages, this will
       # contain exc_name, exc_type and traceback fields.

       # An additional field with supplementary information such as where to
       # send the crash message
       'info' : str,
    }


Future ideas
------------
    
Other potential message types, currently unimplemented, listed below as ideas.
    
Message type: ``file``::

    content = {
	'path' : 'cool.jpg',
	'mimetype' : str,
	'data' : str,
    }

    
Messages on the REQ/REP socket
==============================

This is a socket that goes in the opposite direction: from the kernel to a
*single* frontend, and its purpose is to allow ``raw_input`` and similar
operations that read from ``sys.stdin`` on the kernel to be fulfilled by the
client.  For now we will keep these messages as simple as possible, since they
basically only mean to convey the ``raw_input(prompt)`` call.

Message type: ``input_request``::

    content = { 'prompt' : str }

Message type: ``input_reply``::

    content = { 'value' : str }
    
.. Note::

   We do not explicitly try to forward the raw ``sys.stdin`` object, because in
   practice the kernel should behave like an interactive program.  When a
   program is opened on the console, the keyboard effectively takes over the
   ``stdin`` file descriptor, and it can't be used for raw reading anymore.
   Since the IPython kernel effectively behaves like a console program (albeit
   one whose "keyboard" is actually living in a separate process and
   transported over the zmq connection), raw ``stdin`` isn't expected to be
   available.

   
Heartbeat for kernels
=====================

Initially we had considered using messages like those above over ZMQ for a
kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
alive at all, even if it may be busy executing user code).  But this has the
problem that if the kernel is locked inside extension code, it wouldn't execute
the python heartbeat code.  But it turns out that we can implement a basic
heartbeat with pure ZMQ, without using any Python messaging at all.

The monitor sends out a single zmq message (right now, it is a str of the
monitor's lifetime in seconds), and gets the same message right back, prefixed
with the zmq identity of the XREQ socket in the heartbeat process. This can be
a uuid, or even a full message, but there doesn't seem to be a need for packing
up a message when the sender and receiver are the exact same Python object.

The model is this::

    monitor.send(str(self.lifetime)) # '1.2345678910'

and the monitor receives some number of messages of the form::

    ['uuid-abcd-dead-beef', '1.2345678910']

where the first part is the zmq.IDENTITY of the heart's XREQ on the engine, and
the rest is the message sent by the monitor.  No Python code ever has any
access to the message between the monitor's send, and the monitor's recv.


ToDo
====

Missing things include:

* Important: finish thinking through the payload concept and API.

* Important: ensure that we have a good solution for magics like %edit.  It's
  likely that with the payload concept we can build a full solution, but not
  100% clear yet.

* Finishing the details of the heartbeat protocol.

* Signal handling: specify what kind of information kernel should broadcast (or
  not) when it receives signals.

.. include:: ../links.rst