Scheme for handling virtual documents

[octref]

In #48777, we attempted to limit HTML/CSS extensions to only handling file and untitled schemes. However, this breaks embedded HTML/CSS completions and other language features in Intelephense. It is reverted for release.

Intelephense creates a virtual HTML document and runs command vscode.executeCompletionItemProvider to get list of completions from HTML language server (which includes CSS/JS embedded in HTML).

We should find a way to let languages mark themselves able to handle virtual documents.

[jrieken]

We should find a way to let languages mark themselves able to handle virtual documents.

@octref I don't understand that

[octref]

@jrieken I'm suggesting having a virtual scheme in parallel to file and untitled.

[lostintangent]

@octref What would virtual match? Any document scheme that was defined via the registerTextDocumentContentProvider API? (which presumably accommodates the Intelephense use case?)

But it wouldn't match schemes provides by custom FileSystemProviders? That would be my ideal behavior, since we wouldn't want virtual to automatically match the vsls virtual file system that Live Share registers.

[octref]

@lostintangent

What would virtual match? Any document scheme that was defined via the registerTextDocumentContentProvider API?

Yes. From language server's perspectives if they declare themselves as able to handle file, they may not be able to provide some functionalities for untitled files, which might not exist on disk and not have a path. I think it's the same thing for virtually created files.

For example, the Intelephense extension creates virtual html files out of the PHP files on disk, and call VS Code command vscode.executeCompletionItemProvider to get completions. HTML server is now able to handle it, because our HTML file support is single-file (no understanding of dependencies). However as we add more capabilities to HTML, we might need to selectively enable features for untitled or virtual files. There might be LS which don't want to handle untitled and virtual files, and they should be able to say so.

But it wouldn't match schemes provides by custom FileSystemProviders?

Yep files backed by custom FileSystemProviders still have a fs behind it. Just need to make extension author aware to always use that provider instead of Node's fs.

[jrieken]

@jrieken I'm suggesting having a virtual scheme in parallel to file and untitled.

The problem with that is that there can only one provider per scheme (one truth) and I don't understand who that should be. In other words, you cannot be a document provider anymore but we need to invent another indirection.

TBH, this looks like a dependency between Intelephense and the Html/CSS extension (without explicitly being declared). IMO if we want to constrain Html/CSS to certain schemes then we should have a reasonable default and the Html/CSS extension needs to export API that allows to manage those schemes, e.g. Intelephense calls a function that Html/CSS exports

[aeschli]

One of the main points for virtual documents is to avoid extension dependencies. That allows users to replace our html/css/json extensions. Also the problem is that many more language extensions that are similar to html/css/json would need such an API.

If we want to store meta information for schemes, that could be added to the file system provider or the document providers. What would that information be? 'If you are a language provider, exclude my resources because I guarantee that someone cares for it'?
If that's what you mean, I think that's what @alexandrudima suggested on the liveshare channel with the 'private' flag on file system providers.
I think the idea there is to say that html/css/json still register without any scheme restriction (equivalent to schema: '*'), but what it means is 'all schemes but the private ones'.

[jrieken]

One of the main points for virtual documents is to avoid extension dependencies. That allows users to replace our html/css/json extensions. Also the problem is that many more language extensions that are similar to html/css/json would need such an API.

I understand, but do we have samples/scenarios for both statements? Otherwise I'd suggest to start simple before bringing out the bigger hammer.

Also when did the virtual document renaissance start? Didn't we conclude that it's best to integrate via libraries because its impossible to simply embed a language, e.g. TypeScript with imports embedded inside my new-super-language?

I think the idea there is to say that html/css/json still register without any scheme restriction (equivalent to schema: '*'), but what it means is 'all schemes but the private ones'.

If we do that then this issue resolves itself, right? Isn't the point of Intelephense creating virtual documents that they are not private to the html/css/json extension?

[aeschli]

I understand, but do we have samples/scenarios for both statements? Otherwise I'd suggest to start simple before bringing out the bigger hammer.

We have scenarios and samples. They are all spread in various issues so #47288 is about bringing them together and them to the doc/wiki.
The statement was always that each language is free to choose the way how to deal with embedded languages. Integrate via libraries or use virtual documents. Intelliphense chose the virtual document approach and seem to be happy with it and can live with the limitations.

I suggest to close this issue as we already established that having a well known 'virtual' scheme isn't possible as @jrieken explained in #49069 (comment).

I brought up the 'private' flag as I assume @octref main motivation of the proposal was to find a solution for liveshare. I suggest we better continue the brainstoring and discussion of for a better solution in our liveshare channel. @octref ok to close?