Live share integration

[quoc-ho]

Continue the discussion #4305 (reply in thread).

[hoang06kx1]

Awesome! Great contribution @quoc-ho . Let's wait for review.

[quoc-ho]

The following functionalities have been implemented on guests (on the host, everything is the same as before):

• View pdf by clicking on the pdf file
• View pdf by the view command*
• Auto refresh pdf view when the pdf file changes
• Inverse and forward* synctex

Here, * means doesn't work when the guest is on a Windows computer. This is because on Windows, getPdfPath always returns smth with c:\ at the beginning, which does not make sense. For guests, the input will be something like vsls:/file.tex regardless of the system. I only have limited access to a Windows computer so at least for now, I cannot really troubleshoot this. For now, Windows users can double click on the pdf file to open it instead. Forward synctex is still a problem.

Build command cannot be triggered from the guest yet (but it's not hard to implement). For now, the host can just turn on build on save.

---

Notes on the implementation

1. On the host, everything should function exactly the same as before.
2. There are two minor but very frequent changes involving URI schemes:
   a. Previously, vscode.Uri.file was used, which has file scheme and which doesn't work on the guest side since the appropriate scheme there should be vsls. I implemented fileUriFromPath in file.ts which handles schemes more appropriately.
   b. Previously, there were many checks .scheme === 'file'. I implemented isAcceptedScheme which allows vsls as well and replaced the checks by using this function.
3. On the guest, the HTTP server now switches to proxy mode during a live share session which pipes the requests to the host via the shared port (the share is facilitated by the live share extension). The guest also opens a WebSocket connection to the host WebSocket server and uses this to handle refresh and synctex.
4. When starting a new session, the host will automatically share its port via the live share extension and the guest will automatically obtain that port when joining. Since live share doesn't expose an API to acquire the port (on the guest), it's done via triggering the appropriate command and accessing the clipboard. If the initial sharing fails for some reason (for example, when the host doesn't click allow for the share request), the user can initiate share (on the host) and acquire port (on the guest) via two new commands.

[James-Yu]

I'm back. On it in the next week(s).

[James-Yu]

I did not check carefully (next step will do so), yet it seems that currently synctex from guest to host then back to guest is adding a lot of lines to the code, which is making the code quite convoluted.

I would recommend removing all host-guest communications related to synctex. For guest, rely on its local optionally-installed synctex and fallback to the bundled synctexjs implementation. This will make the code much more maintainable.

[quoc-ho]

Thanks for looking into this. I think the changes are quite minimal. The large changes in synctex.ts are just refactoring. I didn't use the local synctex or synctex.js because the tar.gz file is also unavailable on the guest side due to binary file limitation imposed by LiveShare.

I'm traveling for quite a while so I will be available only for comments if you have questions but probably not actually writing code.

[James-Yu]

I've done some refactoring to follow minimal intrusion. May you have a check if the new code is equivalent when available?

Further, as there are some limited functionalities on Windows, it would be good to have sort of notices when related functions are invoked on win.

[quoc-ho]

Great! I'll go over the refactor by Tuesday.

[quoc-ho]

Sorry for letting this slip. I'm super swamped right now, unfortunately. I'll try to do it soon.

[krokosik]

I would love to see this feature merged. Could I help with the refactor in any way? @quoc-ho @James-Yu

[quoc-ho]

@krokosik I would really love to merge this as well, but I just can't find any time to complete this unfortunately. And things just get harder and harder as time passes because my branch gets more and more out of date and there are probably a lot of conflicts right now. If you can find the time to resolve all the conflicts and test thoroughly, I think you should go ahead!

[krokosik]

@quoc-ho Sure, I'll take a swing at it over the weekend. Do you want me to make another fork or PR or could you add me as a collaborator?

[quoc-ho]

@krokosik Great! I added you as a collaborator.

[krokosik]

@James-Yu I have resolved merge conflicts and added a workaround for Windows. Apparently LiveShare works halfway as a remote VSCode environment, as it uses POSIX paths for its URI scheme, but on the other hand uses the local OS APIs. This is why path.resolve introduces the C: prefix, while the parsed vscode.Uri later converts that to POSIX.

I also added some small comments in liveshare and tested that both PDF refreshing and SyncTex still work. I tried different platform configurations, between Windows, WSL and a DevContainer. Also I noticed the .devcontainer directory still uses Node 16, which does not even allow to build the package anymore, so I updated it to the same version as used in CI. Hope that such a small scope extension is ok with you, but I can also make a separate PR for that.

Thank you so much for creating this extension and I would like to express my willingness to help with merging this as soon as possible. 🙌

[krokosik]

Should I add some information to the wiki/README regarding the feature? In particular the LiveShare host needs to allow port sharing for the integration to work.
We could also mention the OCT extension, which may have less features, but supports binary files out of the box.

[James-Yu]

@krokosik Great work! Before adding docs, please bear me with a few days to check the current implementation. As the changes are too hard to review in its current form, I would propose two things for us to complete:

1. I will make a wrapper function of vscode.Uri.file in file.ts, so that we only need to change this function to include vsls file scheme, reducing the change pollution. This will be reflected in master.
2. May you merge this change to the branch and edit the new file.ts function to cope with vsls file scheme?

After that, I can proceed to review the real changes.

Further, I would suppose there may be an influx of issues regarding liveshare. Would you mind go on maintaining the feature in the following few weeks/months, until it becomes stable? I am very happy to invite new repository collaborators if you are also interested in any other parts of the extension 👍

[James-Yu]

Here it is: d2a77b0

I do think the original getUriScheme is unnecessary: toUri('').scheme should work perfectly.

Further, isUriScheme can be replaced by a new constant in lw.ts and use a .include(scheme) check.

[krokosik]

I'm not sure how to proceed here. It would be nice to have only one constant, like the one in lw.ts, but I guess utils should import close to nothing. This place does not seem like the right place for such a constant, however, the pdfFilePrefix is also duplicated in lw.ts so I decided to also do it.

[krokosik]

@James-Yu I have updated the PR and removed the extra file functions. I also spotted some additional changes that might have appeared due to merges and cleaned them up. I am okay with helping maintain the feature for some time as I would very much like to see it stabilize and admire what you created here and how active you are. I am not that familiar with the general codebase, so I might need your help in Workshop specific details, but would like to help nonetheless.

Also I noticed there are some tests failing, will look into that. I relied on the devcontainer for development and testing as I didn't want to go through installing TexLive on Windows. Similiarly, I would like to use it for running tests, so I added the necessary dependencies to Dockerfiles. Hope this is okay to include in this PR.