Clarify proxy protocol

[zobo]

The proxy protocol is not well defined. One could speculate, that it follows the same line protocol as dbgp (client to server: one line, null terminated / server to client: decimal length, NULL, xml, NULL) however the implementations out there vary in implementation. This makes it hard to implement proxy support into IDEs. Some examples that I was able to find:

pydbgpproxy (Komodo, PhpStorm...) (copy https://github.com/agroszer/komodo-python-dbgp)

• request: reads up to 1024 bytes, trims/strips white space (so sending NULL or newline works)
• response: sends xml, no length or NULLs, then closes connection

https://github.com/MadridianFox/xdebug-proxy

• request: reads until NULL
• response: sends xml, no length or NULLs, then closes connection

https://github.com/mougrim/php-xdebug-proxy

• request: reads until NULL
• response: sends xml, no length or NULLs, then closes connection

https://github.com/eelf/smdbgpproxy/

• request: reads until NULL
• response: sends length NULL xml NULL, then closes connection

I believe more or less everybody uses pydbgpproxy and it's regarded as a defacto standard. The following lines should probably be changed:

The proxy should respond with a simple XML statement alerting the IDE to an error, or the success of the initialization (see section 6.5 for more details on the error element).

to

The proxy should respond with a simple XML statement alerting the IDE to an error, or the success of the initialization and disconnect to indicate all data has been transmitted (see section 6.5 for more details on the error element).

and

Once the IDE has sent this command, and received a confirmation, it disconnects from the proxy.

to

Once the IDE has sent this command, and received a confirmation, the proxy drops the connection.

I can open a PR.

Best,
Damjan

[derickr]

The proxy protocol is not well defined. One could speculate, that it follows the same line protocol as dbgp (client to server: one line, null terminated / server to client: decimal length, NULL, xml, NULL) however the implementations out there vary in implementation.

That's certainly how I think it should work.

It's unfortunate that the section on proxies is done before section 6 (Message Packets). To be fair, the whole draft document should have some proper attention as it's kludgy and not always easy to understand.

I am intending to write a proxy tool myself soon (gives me an excuse to learn Go), and that would certainly use the same protocol as normal DBGp packages — as the proxy things should do too.

[zobo]

Great to hear! There are probably a bunch of implementations in Go already on github, but always great way to learn something new this way. I just worry we'll end up with a split in two worlds, the current py implementation and however you decide to implement it now. I guess it will be up to clients/IDEs to decide what protocol to talk...

[derickr]

FWIW, I found https://github.com/real420og/dbgp-proxy

[zobo]

Ah, a new one.. Shows that all computer problems are already solved, you just need to put it together :)
On a serious note, had a quick look:

• debug side of the protocol doesn't use the message length, just skips to next null byte (https://github.com/real420og/dbgp-proxy/blob/master/handler/debug/debug.go#L33) - will probably work fine
• ide side reads until \0 or EOF (https://github.com/real420og/dbgp-proxy/blob/master/handler/ide/ide.go#L25) ignoring a possible message length prefix..

Again using the de-facto standard for IDE protocol...