Add far2l terminal extensions support

[unxed]

This issue was originally dedicated to OSC 52 support, but it is about implementing far2l terminal extensions support now. For OSC 52 support see #356

---

For example,

echo -e "\033]52;c;$(base64 <<< hello)\a"

should send "hello" to clipboard. More detailed explanations:

mintty/mintty#258 (comment)
https://bugs.kde.org/show_bug.cgi?id=372116
https://gitlab.gnome.org/GNOME/vte/-/issues/125
microsoft/terminal#2946

[lars18th]

Hi @cyd01 ,

This functionality seems interesting. Can you check it?

[unxed]

There is also competing clipboard access method for terminals, it is used in linux port of Far Manager (https://github.com/elfmz/far2l), so called "far2l terminal extensions", but those are completely undocumented and not very popular outside far2l (only one external supporting client is known for now, https://github.com/unxed/putty4far2l). Those extensions provide not only clipboard but also full keyboard support (keyup/keydown, all modifiers, etc).

Still I (as the author of putty4far2l) can try to document them if someone is interested.

[lars18th]

Hi @unxed ,

Still I (as the author of putty4far2l) can try to document them if someone is interested.

My suggestion is then: try to document it and provide a PR for KiTTY if you can. If you need help with the code of KiTTY then ask to @cyd01 .

Regards.

[MrM40]

Would be nice to be able to interact with the clipboard from the terminal.

I expect there is a little chance the requested documentation for "far2l terminal extensions" will surface.

The OSC-52 code from the kovidgoyal/kitty seem to be available here:
kovidgoyal/kitty@889ca77
(don't know if that code is helpful)

[unxed]

I expect there is a little change the requested documentation for "far2l terminal extensions" will surface.

Protocol is very simple, but to explain it, I need to digg into the code I wrote a half a year ago. Will try to find some time for it. Maybe it is reasonable to start right now and add some little pieces from time to time, so let's go :)

First of all. Far2l extensions use APC (Application Program Command) escape sequences, so all of them starts with "\x1b_".

Next goes sequence header (string "far2l0" or "far2l1" or "far2l:" for server->client sequences, "far2l" or "f2l" for client->server sequences - shorter "f2l" version is used for input events to save traffic). After it goes actual payload that is stack-like structure [VARIABLE1][VARIABLE2][VARIABLE3] etc, encoded in base64 format (exceptions for server->client communication are "far2l0" and "far2l1" that have no payload at all, client->server "far2lok" has no payload also).

Each sequence is finished with "\x07".

When far2l is launched on the server side, it tries to turn on special "far2l extensions" mode on client (in this mode keyboard keys and mouse events should be sent as far2l sequences and not in common way) by sending "\x1b_far2l1\x07". Client should reply with "\x1b_far2lok\x07", this means far2l mode is supported and turned on.

If client receives "\x1b_far2l0\x07", that means it should turn extensions mode off and send keyboard and mouse events as usual.

All other server-to-client sequences starts with "\x1b_far2l:", and there are several types of them (event type is always last variable in payload stack for such sequences): "n" - show desktop notification, "w" - get largest console window size, "c" - clipboard interaction, etc.

Will explain each of those sequence types and also client-to-server sequences in further comments. Please remind several days later!

Also @elfmz, far2l author, is welcomed to help with documenting this :)

UPD: Original implementation, terminal part:
https://github.com/elfmz/far2l/blob/master/far2l/VTFar2lExtensios.cpp
Terminal application part:
https://github.com/elfmz/far2l/blob/master/WinPort/src/Backend/TTY/TTYBackend.cpp
(code paths where _far2l_tty flag is enabled)

[unxed]

Trying to document far2l terminal extensions, part II

Virtual terminal -> console application (client -> server) events:

1. KeyDown

KeyDown event's message payload consists of the following variables:

RepeatCount: 2 bytes, pressed key repeat count as defined in KEY_EVENT_RECORD struct
VirtualKeyCode: 2 bytes, virtual key code for pressed key as defined in KEY_EVENT_RECORD struct
VirtualScanCode: 2 bytes, virtual scan code for pressed key as defined in KEY_EVENT_RECORD struct
ControlKeyState: 4 bytes, modifiers state as defined in KEY_EVENT_RECORD struct
UnicodeChar: 4 bytes, corresponding unicode char for keypress as defined in KEY_EVENT_RECORD struct
MessageType: 1 byte, always 'K'

There is special case with keys VK_TAB, VK_BACK, VK_ESCAPE, VK_DELETE.
For whose keys VitualScanCode should be sent as zero, or far2l plugin "editor autocomplete" will stop working. It is just a workaround for buggy plugin and should not be considered as standard behavior.

Example 1, "t" key down.

RepeatCount = 1
VirtualKeyCode = 84 ("T")
VitualScanCode = 20
ControlKeyState = 0
UnicodeChar = 116 ("t")
MessageType = 75 ("K")

base64-encoded message: AQBUABQAAAAAAHQAAABL
Full ESC sequence: \x1b_f2lAQBUABQAAAAAAHQAAABL\x07

Example 2, Ctrl+ArrowUp keys down.

RepeatCount = 1
VirtualKeyCode = 38
VitualScanCode = 72
ControlKeyState = 8
UnicodeChar = 0
MessageType = 75 ("K")

base64-encoded message: AQAmAEgACAAAAAAAAABL
Full ESC sequence: \x1b_f2lAQAmAEgACAAAAAAAAABL\x07

Example of how to construct corresponding message in windows WM_KEYUP/WM_KEYDOWN handler can be found here:
https://github.com/unxed/putty4far2l/blob/90a8448d914a08bd28ff28f60808fda318ca7b0b/windows/window.c#L3212

2. KeyUp

Just the same as KeyDown, but MessageType is "k" instead of "K".

[systemmonkey42]

Has there been any progress or interest in supporting OSC 52 clipboard access?

Its long overdue as a feature.

If I understand the commands correctly, they are basically:

1. OSC 52 ; <x> ; base64 data ST for setting clipboard data, (where <x> selects the clipboard or buffer, and
2. OSC 52 ; <x>; ? ST for accessing the clipboard and sending to the terminal encoded in the same format which could be used to set the clipboard.

From a quick browse of the source, I see three issues;

1. Need to add a feature flag to disable host clipboard access for security reasons
2. OSC 52 ; x ; <data> ST provides x to indicate which clipboard/buffer. Windows only has a single clipboard so this can be ignored
3. The <data> portion is limited to OSC_STR_MAX which is 2048 bytes which includes the ;x; clipboard selection option characters and the clipboard data in base64, which reduces the clipboard to about 1533 usable characters.

I'm happy to put in a little time to implement this if it seems worthwhile.

I'm not 100% comfortable it will be all that usable with a 1533(ish) character limit, and unicode may pose challenges.

It may require making OSC_STR_MAX dynamic,, and using malloc()/realloc()/free() to manage the available buffer space.

EDIT: detail

[unxed]

Trying to document far2l terminal extensions, part II

Now we have far2l terminal extensions protocol somewhat explained here:
https://github.com/elfmz/far2l/blob/master/WinPort/FarTTY.h

[unxed]

far2l extensions support for kitty 0.76.0.6, patch
code authored by @unxed, @elfmz, @mihmig

far2l_extensions_kitty_0.76.0.6.tar.gz

[lars18th]

Hi @unxed ,

far2l extensions support for kitty 0.76.0.6, patch code authored by @unxed, @elfmz, @mihmig

I recommend to create a PR with this patch.

[unxed]

That's great! I just need some time to make comments little more informative and remove commented out debug stuff.

[unxed]

PR will be from https://github.com/mihmig/KiTTY as adoption of my putty patch for KiTTY was done by @mihmig

[unxed]

Let's split issues now. This will stay about far2l extensions support. OSC 52 is different feature, so it should be discussed in a separate issue, #356

[mihmig]

Created PR:
#357

[unxed]

PR was merged with some minor problems preventing far2l extensions from actually working. This new PR fixes them: #363

[unxed]

far2l extensions working since cef8eec, closing. For OSC 52 support see #356