Addon documentation for intercepting socket data.

[hatched]

It would be great if there was some documentation on how to interact with xterm via a plugin, not simply just registering one.

With the new addon change in v4 the old terminado plugin no longer appears to work. I'm not able to find any documentation on how to write such a plugin which requires, aiui, intercepting the incoming and outgoing messages to format them into a structure that makes sense to display to the user.

The old plugin appears to clobber a few internal methods which no longer exist.

Thanks!

[jerch]

@hatched From IO viewpoint there is not much magic going on - the terminal has a write method for incoming, and an onData event for outgoing data. This and other public parts are documentend in the terminal API here or here.

Imho the terminado plugin could be adopted to v4 easily (to get the idea see the attach addon). Note that we had to remove the terminado plugin from our codebase as it was not actively maintained.

[hatched]

Thanks for the reply @jerch

I had a similar idea and took the existing attach addon and modified it to send and receive the proper data format for Terminado. It's still very much a WIP but it's functional.

I think the root of the issue was that I was expecting to interact with the terminal instance from the addon, not creating the websocket communication layer. So I was looking for some type of a middleware api. Once I approached it from this other angle it was quite trivial 👍

[hatched]

It's my intention that once it's sufficiently stable to put it on npm, unless you'd like it contributed back to the project? It'll be written in JS not TS.

[Tyriar]

@hatched probably best to live under your user but we can link to it. We had a terminado addon earlier and decided to put it out as we couldn't maintain it.

[Tyriar]

I think this issue can be closed?

[FrancYescO]

@hatched do you have anything to share?

Still not clear what is the correct way to have Terminado working with v4

[jerch]

@FrancYescO Whats the problem with terminado, whats unclear on its end?

Edit:
As far as I can see, you only have to patch some the terminal method to v4 semantics in https://github.com/jupyter/terminado/blob/master/terminado/_static/terminado.js, like on('data', ...) --> onData(...). Furthermore you will need another message type for non-UTF8 encodable stuff from the terminal like ancient mouse protocol coords (can be grabbed with term.onBinary(...)). Everything else can stay as it is.

Ofc there are further improvements possible (like switching to bytearray websocket transfer, which is abit faster), but that depends on how terminado/tornado wants to deal with data on server side. Or even more complicated stuff like multiple terminal session over just one socket, flow control and what else.

[FrancYescO]

@jerch sincerely, what i was struggling for is trying to use AttachAddon with terminado, do you suggest to just manage the ws connection directly?

[jerch]

@FrancYescO I cannot answer that for you, it depends too much on outer constraints like additional protocol stack you want transport over the socket. The attach addon itself is bare metal in this regard, it does not deal with things like authentication/authorization, thus should not be used in production envs without further security measures. But thats beyond the scope of xterm.js, as it always involves special preparations on server side as well. Same with proper flow control.

[FrancYescO]

Actually my main objective is to upgrade from the v3 of xterm (using the terminado addon) leaving untouched the ws server (using tornado), so basically i give up with the AttachAddon.
I've updated the code of make_terminal, and i'm directly managing the connection using a v4 xterm, it was pretty simple:

      ws.onopen = function() {
        ws.send(
          JSON.stringify([
            "set_size",
            term.rows,
            term.cols,
            window.innerHeight,
            window.innerWidth
          ])
        );
        term.onData(data => {
          ws.send(JSON.stringify(["stdin", data]));
        });

        term.onTitleChange(title => {
          document.title = title;
        });

        term.open(document.getElementById(HtmlId));
        term.focus();

        ws.onmessage = function(event) {
          const jsonMsg = JSON.parse(event.data);
          switch (jsonMsg[0]) {
            case "stdout":
              term.write(jsonMsg[1]);
              break;
            case "disconnect":
              term.write("\r\n\r\n[Finished... Terminado]\r\n");
              break;
            default:
              break;
          }
        };
      };

actually the only missing thing seems the cursor not moving

[jerch]

actually the only missing thing seems the cursor not moving

Maybe missing the CSS file?

[FrancYescO]

oww, yes, also that, was that easy, thanks!