Add documentation for the EternalTerminal protocol

[jwmcglynn]

To better understand the protocol and to support future changes, add a first draft of documentation for the protocol between et, etserver, and etterminal.

[jwmcglynn]

See a rendered version of the docs here: https://github.com/jwmcglynn/EternalTerminal/blob/docs/docs/protocol.md

Feedback and suggestions are welcome.

[codecov-commenter]

Codecov Report

Merging #523 (3d9ef41) into master (eca37f3) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #523   +/-   ##
=======================================
  Coverage   71.27%   71.27%           
=======================================
  Files          49       49           
  Lines        3074     3074           
=======================================
  Hits         2191     2191           
  Misses        883      883           

Impacted Files	Coverage Δ
src/base/ServerClientConnection.cpp	92.85% <0.00%> (-3.58%)	⬇️
src/base/Connection.cpp	86.08% <0.00%> (-2.61%)	⬇️
test/ConnectionTest.cpp	94.44% <0.00%> (-0.51%)	⬇️
src/base/RawSocketUtils.cpp	38.70% <0.00%> (+16.12%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update eca37f3...3d9ef41. Read the comment docs.

[MisterTea]

Wow, awesome! I added a section for port forwarding as a review comment.

[MisterTea]

Suggested change

	Port forwarding is supported in eternal terminal using the same connection that transmits the terminal updates. To forward ports, one passes the `-t` option followed by a list of ports and/or port ranges. Some examples:
	`et -x -t "8080:8080" myuser@myhost`
	`et -x -t "2222:22" myuser@myhost`
	`et -x -t "8080-8089:8080-8089" myuser@myhost`
	When passing -t, it's also advisable to pass -x as well. Trying to create a second port forward to the same destination will fail.
	Reverse tunnels are also allowed (this allows the server to connect to your client machine on the specified ports). Examples:
	`et -x -r "8080:8080" myuser@myhost`
	`et -x -r "2222:22" myuser@myhost`

[jwmcglynn]

Thanks! I've used this as a template and filled out the port forwarding section, and included a few more features.

By the way, did you know that specifying unix sockets using forward tunnels crashes?

et -t MY_ENV:/var/log/docker.sock myserver

I don't know how this would work compared to reverse tunnels, since setting $MY_ENV is not helpful, but right now it crashes. At least on my mac client:

[FATAL 2022-06-30 01:23:37,399 client-main PortForwardHandler.cpp:63] Stack Trace: 
[0] 0x7e3f80010002bd54 et::PortForwardHandler::createSource(et::PortForwardSourceRequest const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >*, unsigned int, unsigned int)
[1] 0x724a0001000360f0 et::TerminalClient::TerminalClient(std::__1::shared_ptr<et::SocketHandler>, std::__1::shared_ptr<et::SocketHandler>, et::SocketEndpoint const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&, std::__1::shared_ptr<et::Console>, bool, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&, bool, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&, int)
[2] 0xc11a8001000100b8 main
Tried to create a pipe but without a place to put the name!

I've also found that using -x is not 100% reliable, since the port forwarding is handled by etserver and not the etterminal, so there is a bit of a delay before ports are released after the terminal is killed.

[MisterTea]

Yeah, that is the number one crasher right now. I put a delay in the connect to fix but it isn't reliable. We need to fix the race condition somehow.

Forward tunnel unix sockets should probably just be disabled, but I don't think anyone has tried it besides you so it isn't super high pri.

[jwmcglynn]

I am drafting a v7 protocol proposal now, and as part of that I'd like to move port forwarding to the etterminal process.

I think that would fix the race condition, assuming that the kernel releases sockets immediately.

[MisterTea]

I don't think the kernel does release them immediately?

But we could have some back-off logic

[jwmcglynn]

Ok, I fixed some errors and split the connection flow mermaid diagrams. I think this is good to go and I plan on merging this later today.