=====================
Message Specification
=====================

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.

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.


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
=====================

General message format::

    {
        header : { 'msg_id' : 10,    # start with 0
	           'username' : 'name',
		   'session' : uuid
		   },
	parent_header : dict,
        msg_type : 'string_message_type',
        content : blackbox_dict , # Must be a dict
    }

    
Request/Reply going from kernel for stdin
=========================================

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 : string }

Message type: 'input_reply'::

    content = { value : string }

    
Side effect: (PUB/SUB)
======================

Message type: 'stream'::

    content = {
	name : 'stdout',
	data : 'blob',
    }

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.
    
Message type: 'pyin'::

    content = {
	code = 'x=1',
    }

Message type: 'pyout'::

    content = {
	data = 'repr(obj)',
	prompt_number = 10
    }

Message type: 'pyerr'::

    content = {
       # Same as the data payload of a code execute_reply, minus the 'status'
       # field. See below.
    }

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 = {
	traceback : 'full traceback',
	exc_type : 'TypeError',
	exc_value :  'msg'
    }


Other potential message types, currently unimplemented, listed below as ideas.
    
Message type: 'file'::
    content = {
	path : 'cool.jpg',
	mimetype : string
	data : 'blob'
    }

    
Request/Reply
=============

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.  Some thought is still required here...

Message type: 'execute_request'::

    content = {
	code : 'a = 10',
    }

Reply:

Message type: 'execute_reply'::

    content = {
      'status' : 'ok' OR 'error' OR 'abort'
      # 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 : string
	    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' : number

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

      # This 'payload' needs a bit more thinking.  The basic idea is that
      # certain actions will want to return additional information, such as
      # magics producing data output for display by the clients.  We may need
      # to define a few types of payload, or specify a syntax for the, not sure
      # yet... FIXME here.
      'payload' : things from page(), for example.
    }

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

    {
      etype : str   # Exception type, as a string
      evalue : 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 of strings
    }


When status is 'abort', there are for now no additional data fields.


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 : string
      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. 
    
    
Complete
--------

Message type: 'complete_request'::

    content = {
	text : 'a.f',    # complete on this
	line : 'print a.f'    # full line
    }

Message type: 'complete_reply'::

    content = {
	matches : ['a.foo', 'a.bar']
    }

    
History
-------

For clients to explicitly request history from a kernel

Message type: 'history_request'::

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

      range : optional. 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

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

Message type: 'history_reply'::

    content = {
      input : list of pairs (number, input)
      output : list of pairs (number, output). Empty if not requested.
      }


Control
-------

Message type: 'heartbeat'::

    content = {
    # XXX - unfinished
    }