Simplify settings handling, delegate to workspace/configuration
#106
Conversation
dhruvmanila
changed the title
workspace/configuration
dhruvmanila
force-pushed
the
dhruv/simplify-settings
branch
from
ead7a07 to
e0e2c5c
Compare
|
Just for my understanding. Is this a breaking change only because of:
Or are there other breaking changes? |
There was a problem hiding this comment.
Will this break backwards compatibility with older ty binaries? E.g. will the extension stop working if someone uses an older ty version that doesn't support the changes of your linked PR? If so, could we support backwards compatibility (at least basic backwards compatibility) or show an update notice?
No, that's the only one.
Yes, it will break backwards compatibility because How does that sound? |
|
I'm fine breaking backwards compatibility as long as it doesn't prevent the server from starting (which it might). Unless we can provide a good error message (so that it's easy for users to fix) |
I don't think it'll prevent the server from starting because we'll then use the default initialization options if the deserialization failed. |
|
So, I tested out two combinations here:
For (1), instead of graying out, I'm writing the deprecation message as in For (2), I'll open an issue in ty to make the settings deserialization strict using |
Could we use the extra fields hash map trick? It would be nice to only warn users about unknown fields but still deserialize the known settings. |
|
## Summary This PR implements support for providing LSP client settings. The complementary PR in the ty VS Code extension: astral-sh/ty-vscode#106. Notes for the previous iteration of this PR is in #19614 (comment) (click on "Details"). Specifically, this PR splits the client settings into 3 distinct groups. Keep in mind that these groups are not visible to the user, they're merely an implementation detail. The groups are: 1. `GlobalOptions` - these are the options that are global to the language server and will be the same for all the workspaces that are handled by the server 2. `WorkspaceOptions` - these are the options that are specific to a workspace and will be applied only when running any logic for that workspace 3. `InitializationOptions` - these are the options that can be specified during initialization The initialization options are a superset that contains both the global and workspace options flattened into a 1-dimensional structure. This means that the user can specify any and all fields present in `GlobalOptions` and `WorkspaceOptions` in the initialization options in addition to the fields that are _specific_ to initialization options. From the current set of available settings, following are only available during initialization because they are required at that time, are static during the runtime of the server and changing their values require a restart to take effect: - `logLevel` - `logFile` And, following are available under `GlobalOptions`: - `diagnosticMode` And, following under `WorkspaceOptions`: - `disableLanguageServices` - `pythonExtension` (Python environment information that is populated by the ty VS Code extension) ### `workspace/configuration` This request allows server to ask the client for configuration to a specific workspace. But, this is only supported by the client that has the `workspace.configuration` client capability set to `true`. What to do for clients that don't support pulling configurations? In that case, the settings needs to be provided in the initialization options and updating the values of those settings can only be done by restarting the server. With the way this is implemented, this means that if the client does not support pulling workspace configuration then there's no way to specify settings specific to a workspace. Earlier, this would've been possible by providing an array of client options with an additional field which specifies which workspace the options belong to but that adds complexity and clients that actually do not support `workspace/configuration` would usually not support multiple workspaces either. Now, for the clients that do support this, the server will initiate the request to get the configuration for all the workspaces at the start of the server. Once the server receives these options, it will resolve them for each workspace as follows: 1. Combine the client options sent during initialization with the options specific to the workspace creating the final client options that's specific to this workspace 2. Create a global options by combining the global options from (1) for all workspaces which in turn will also combine the global options sent during initialization The global options are resolved into the global settings and are available on the `Session` which is initialized with the default global settings. The workspace options are resolved into the workspace settings and are available on the respective `Workspace`. The `SessionSnapshot` contains the global settings while the document snapshot contains the workspace settings. We could add the global settings to the document snapshot but that's currently not needed. ### Document diagnostic dynamic registration Currently, the document diagnostic server capability is created based on the `diagnosticMode` sent during initialization. But, that wouldn't provide us with the complete picture. This means the server needs to defer registering the document diagnostic capability at a later point once the settings have been resolved. This is done using dynamic registration for clients that support it. For clients that do not support dynamic registration for document diagnostic capability, the server advertises itself as always supporting workspace diagnostics and work done progress token. This dynamic registration now allows us to change the server capability for workspace diagnostics based on the resolved `diagnosticMode` value. In the future, once `workspace/didChangeConfiguration` is supported, we can avoid the server restart when users have changed any client settings. ## Test Plan Add integration tests and recorded videos on the user experience in various editors: ### VS Code For VS Code users, the settings experience is unchanged because the extension defines it's own interface on how the user can specify the server setting. This means everything is under the `ty.*` namespace as usual. https://github.com/user-attachments/assets/c2e5ba5c-7617-406e-a09d-e397ce9c3b93 ### Zed For Zed, the settings experience has changed. Users can specify settings during initialization: ```json { "lsp": { "ty": { "initialization_options": { "logLevel": "debug", "logFile": "~/.cache/ty.log", "diagnosticMode": "workspace", "disableLanguageServices": true } }, } } ``` Or, can specify the options under the `settings` key: ```json { "lsp": { "ty": { "settings": { "ty": { "diagnosticMode": "openFilesOnly", "disableLanguageServices": true } }, "initialization_options": { "logLevel": "debug", "logFile": "~/.cache/ty.log" } }, } } ``` The `logLevel` and `logFile` setting still needs to go under the initialization options because they're required by the server during initialization. We can remove the nesting of the settings under the "ty" namespace by updating the return type of https://github.com/zed-extensions/ty/blob/db9ea0cdfd7352529748ef5bf729a152c0219805/src/tychecker.rs#L45-L49 to be wrapped inside `ty` directly so that users can avoid doing the double nesting. There's one issue here which is that if the `diagnosticMode` is specified in both the initialization option and settings key, then the resolution is a bit different - if either of them is set to be `workspace`, then it wins which means that in the following configuration, the diagnostic mode is `workspace`: ```json { "lsp": { "ty": { "settings": { "ty": { "diagnosticMode": "openFilesOnly" } }, "initialization_options": { "diagnosticMode": "workspace" } }, } } ``` This behavior is mainly a result of combining global options from various workspace configuration results. Users should not be able to provide global options in multiple workspaces but that restriction cannot be done on the server side. The ty VS Code extension restricts these global settings to only be set in the user settings and not in workspace settings but we do not control extensions in other editors. https://github.com/user-attachments/assets/8e2d6c09-18e6-49e5-ab78-6cf942fe1255 ### Neovim Same as in Zed. ### Other Other editors that do not support `workspace/configuration`, the users would need to provide the server settings during initialization.
## Summary This PR updates the documentation to reflect the changes made in astral-sh/ruff#19614 and astral-sh/ty-vscode#106. ## Test Plan <details><summary>Screenshot of the new editor settings reference page:</summary> <p> <img width="4992" height="3702" alt="image" src="https://github.com/user-attachments/assets/e3afd5a3-8b5b-43c3-addd-e1d6636ab1b7" /> </p> </details>
Summary
Related PR for ty server: astral-sh/ruff#19614
This PR simplifies the settings handling in the extension by:
IInitializationOptionswithInitializationOptionsthat only containslogLevelandlogFileworkspace/configurationrequestISettingstoExtensionSettingsas now that only contains settings specific to VS Codepython.ty.disableLanguageServicestoty.disableLanguageServicesTest Plan
Refer to the test plan in astral-sh/ruff#19614 specific to VS Code.