rfc24: add optional encoding override in data events

Problem: It is unnecessarily restrictive to require that all data
events for a particular stream are bound to a single encoding. Allowing
the encoding to be overridden per-event would allow easy escaping
of invalid characters on a per-event basis. Knowledge that a data
stream cannot be encoded using the header-specified encoding may not
be known until runtime, at which point it is too late to go back and
change the encoding type.

Specify that any encoding specified in the header event is the
"default" encoding for a stream, implying that the encoding might
be overridden.

Allow an optional "encoding" key in the data context object. If set,
this encoding will be considered to override the default encoding
for that stream, and will apply to the current data event only.

Author: grondo

spec_24.rst

@@ -83,7 +83,7 @@ version
 
 encoding
    (object) A dictionary mapping stream names (e.g. ``stdin``, ``stdout``, ``stderr``)
-   to encoding type (e.g. ``base64``, ``UTF-8``).
+   to default encoding type (e.g. ``base64``, ``UTF-8``).
 
 count
    (object) A dictionary mapping stream names (e.g. ``stdout``, ``stderr``)
@@ -146,6 +146,12 @@ data
 eof
    (boolean) End of stream indicator.
 
+The following keys are OPTIOINAL in the event context object:
+
+encoding
+   (string) The encoding of this particular data event when different from
+   the default encoding specified by the header event.
+
 The context object SHOULD contain either a ``data`` or ``eof`` key, or both.
 
 Example: