Skip to content

Commit

Permalink
Clarify property name encodings
Browse files Browse the repository at this point in the history 
- 6.0 Added section detailing escaping rules for sending arguments to the
  debugger engine. Specifically crafted to prevent confusion around sending
  property names.
- 7.11 Clarify that IDEs must not apply any default escaping rules to
  read/write properties through property_get, property_set, and
  property_value.
- 7.11.1 Added header and describe extended properties better.
  • Loading branch information
@derickr
derickr committed Jan 10, 2018
1 parent 14ff840 commit 2180e4b
Showing 1 changed file with 112 additions and 28 deletions.
140 changes: 112 additions & 28 deletions debugger_protocol.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ DBGP - A common debugger protocol for languages and debugger UI communication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Version: 1.0
:Status: draft 20
:Status: draft 21
:Authors: - Shane Caraveo, ActiveState <shanec@ActiveState.com>
- Derick Rethans <derick@derickrethans.nl>

Expand Down Expand Up @@ -352,7 +352,8 @@ with a stringified integer representing the number of bytes in the XML data
packet. The length and XML data are separated by a NULL byte. The
XML data is ended with a NULL byte. Neither the IDE or debugger engine
packets may contain NULL bytes within the packet since it is used as
a separator. Data must be encoded using base64. ::
a separator. The IDE to debugger engine ``data`` element (behind ``--``) MUST
be encoded using base64. ::

IDE: command [SPACE] [args] -- data [NULL]
DEBUGGER: [NUMBER] [NULL] XML(data) [NULL]
Expand All @@ -363,17 +364,8 @@ or Pythons Cmd module: ::

command -a value -b value ...

If a value for an option includes a space, the value needs to be
encoded. You can encode values by encasing them in double quotes::

property_get -i 5 -n "$x['a b']" -d 0 -c 0 -p 0

It is also possible to use escape characters in quoted strings::

property_get -i 6 -n "$x[\"a b\"]" -d 0 -c 0 -p 0

All numbers in the protocol are base 10 string representations, unless
the number is noted to be debugger engine specific (eg. the address
the number is noted to be debugger engine specific (e.g. the address
attribute on property elements).

6.1 Why not XML both ways?
Expand Down Expand Up @@ -444,10 +436,13 @@ is not an example of the actual protocol.) ::
6.3 IDE to debugger engine communications
-----------------------------------------

A debugging IDE (IDE) sends commands to the debugger engine in
the form of command line arguments. One argument that is included in
all commands is the data length. The data itself is the last part of
the command line, after the -- separator. The data must be base64 encoded. ::
A debugging IDE (IDE) sends commands to the debugger engine in the form of
command line arguments.

Some comments support a ``data`` argument that is included at the end of the
"command line". This data is included in the packet's data length.
The data itself is the last part of the command line, after the -- separator.
The data must be base64 encoded::

command [SPACE] [arguments] [SPACE] -- base64(data) [NULL]

Expand All @@ -456,6 +451,59 @@ Standard arguments for all commands ::
-i Transaction ID
unique numerical ID for each command generated by the IDE

All the other arguments depend on which ``command`` is being sent.

6.3.1 Escaping Rules
--------------------

If a value for an option includes a space or NULL character, the IDE MUST
encapsulate the value in double quotes (``"``)::

property_get -i 5 -n "$x['a b']"

In other cases, the value MAY be encapsulated in double quotes::

property_get -i 6 -n "$x['ab']"

Inside a double-quoted argument, the double-quote (``"``), back-slash (``\``)
and NULL character (*chr(0)*) MUST be escaped with a back-slash. Single quotes
(``'``) MAY be escaped.

Escaping double-quote and single-quote::

property_get -i 7 -n "$x[\"a b\"]"
property_get -i 8 -n "$x['a b']"
property_get -i 9 -n "$x[\'a b\']"

Most languages don't support this, but we have if we have a NULL character in
the string, like in ``$x`` *chr(0)* ``y``, or, ``$x->f`` *chr(0)* ``oo``, than
they need to be quoted with a back-slash (``\``), as in::

property_get -i 10 -n "$x\0y"
property_get -i 11 -n "$x->f\0oo"

If the NULL character is already escaped according to a language, for example,
as part of an array element key, then there is no un-escaped NULL character in
the string any more, and hence does not need to be escaped again.

The Debugging Engine in this case would already have returned the XML
attribute value ``$x[&quot;a\0b&quot;]`` [*]_, where the *chr(0)* is already
escaped as ``\0``.

XML decoding this gives ``$x["a\0b"]``, which can be used as argument as
either one of::

property_get -i 12 -n $x["a\0b"]
property_get -i 13 -n "$x[\"a\\0b\"]"

.. [*] With the ``extended_properties`` feature set to ``1``, the IDE would
not have sent ``$x[&quot;a\0b&quot;]`` as attribute value, but rather
it would have used
``<fullname
encoding="base64"><![CDATA[JHhbImFcMGIiXQ==]]></fullname>``, as the
*chr(0)* in the **name** property would have triggered the use of
base64 encoded XML element values.
6.4 debugger engine to IDE communications
-----------------------------------------

Expand Down Expand Up @@ -1399,8 +1447,11 @@ debugger engine ::
Properties that have children may return an arbitrary depth of
children, as defaulted by the debugger engine. A maximum depth
may be defined by the IDE using the feature_set command with the
max_depth argument. The IDE may then use the fullname attribute of
a property to dig further into the tree. Data types are defined
max_depth argument. The IDE MAY then use the fullname attribute of
a property to dig further into the tree with ``property_get``,
``property_set`` and ``property_value``. An IDE MUST NOT apply any escaping
rules to the ``fullname`` attribute except for the escaping rules as are
explained in `6.3.1 Escaping Rules`_. Data types are defined
further in section 7.12 below.

The number of children sent is defined by the debugger engine unless
Expand Down Expand Up @@ -1432,14 +1483,20 @@ Attributes in the property element can include:
Attribute Description
=============== ========================================================
name variable name. This is the short part of the
name. For instance, in PHP:
name, and is meant to be displayed in the IDE's UI.
For instance, in PHP:
$v = 0; // short name 'v'
class:$v; // short name 'v'
fullname variable name. This is the long form of the name
which can be eval'd by the language to retrieve
the value of the variable. IDEs SHOULD NOT use the eval
command to retrieve nested properties with this, but
instead use property_get.
$object->v; // short name 'v'
fullname variable name. This is the long form of the name,
which, once XML-decoded, can be used by the IDE to
retrieve the value of the variable trough
``property_get`` or ``property_value``, following the
`6.3.1 Escaping Rules`_ for IDE to Debugger Engine
communications. Although it resembles the
language's own syntax to describe and evaluate a variable
name, IDEs SHOULD NOT use the ``eval`` command to retrieve
nested properties with this, but instead use
``property_get``.
$v = 0; // long name 'v'
class::$v; // short name 'v', long 'class::$v'
$this->v; // short name 'v', long '$this->v'
Expand Down Expand Up @@ -1473,9 +1530,26 @@ Attributes in the property element can include:
with this attribute set
=============== ========================================================

If the name attribute is *not set*, then the property element structure is
required to provide name, fullname (optional), classname (optional) and value
as sub elements of the <property> element::
7.11.1 Extended Properties
^^^^^^^^^^^^^^^^^^^^^^^^^^

If the debugger engine and IDE have negotiated to use extended properties
(through ``feature_set -n extended_properties``), then a debugging engine MAY
use the extended property return type defined here.

A debugging engine MUST use this format if either the name, fullname, or
classname values can not be encoded in XML, but *only* when extended
properties are negotiated with the IDE.

If extended properties are not negotiated, a debugger engine MUST NOT use this
format, but instead use the normal format, even if this means returning
invalid XML to IDEs.

An IDE can detect that a debugger engine has sent this extended format, by
detecting that the ``name`` attribute on the ``property`` element is missing.
If the name attribute is *not set*, then a debugger engine MUST provide name,
fullname (optional), classname (optional) and value as sub elements of the
<property> element, and encode their values in base64::

<property
type="data_type"
Expand Down Expand Up @@ -2277,6 +2351,16 @@ where,
A. ChangeLog
============

2018-01-09 - draft 21

- 6.3.1 Added section detailing escaping rules for sending arguments to the
debugger engine. Specifically crafted to prevent confusion around sending
property names.
- 7.11 Clarify that IDEs must not apply any default escaping rules to
read/write properties through property_get, property_set, and
property_value.
- 7.11.1 Added header and describe extended properties better.

2017-07-10 - draft 20

- 5.3 Fixed the text and example for proxyinit. It doesn't accept "-a ip:port"
Expand Down

0 comments on commit 2180e4b

Please sign in to comment.