mirror of
https://github.com/enso-org/enso.git
synced 2024-12-23 15:21:48 +03:00
Update Language Server API for Libraries (#1853)
This commit is contained in:
Radosław Waśko
GitHub
parent
2eadf9f19f
commit
8f57d67bc6
@ -58,6 +58,8 @@ transport formats, please look [here](./protocol-architecture).
|
||||
- [`EnsoDigest`](#ensodigest)
|
||||
- [`FileSegment`](#filesegment)
|
||||
- [`ContentRoot`](#contentroot)
|
||||
- [`LibraryEntry`](#libraryentry)
|
||||
- [`EditionReference`](#editionreference)
|
||||
- [Connection Management](#connection-management)
|
||||
- [`session/initProtocolConnection`](#sessioninitprotocolconnection)
|
||||
- [`session/initBinaryConnection`](#sessioninitbinaryconnection)
|
||||
@ -90,8 +92,6 @@ transport formats, please look [here](./protocol-architecture).
|
||||
- [`file/checksum`](#filechecksum)
|
||||
- [`file/checksumBytes`](#filechecksumbytes)
|
||||
- [`file/event`](#fileevent)
|
||||
- [`file/addRoot`](#fileaddroot)
|
||||
- [`file/removeRoot`](#fileremoveroot)
|
||||
- [`file/rootAdded`](#filerootadded)
|
||||
- [`file/rootRemoved`](#filerootremoved)
|
||||
- [Text Editing Operations](#text-editing-operations)
|
||||
@ -147,13 +147,26 @@ transport formats, please look [here](./protocol-architecture).
|
||||
- [`io/standardErrorAppended`](#iostandarderrorappended)
|
||||
- [`io/feedStandardInput`](#iofeedstandardinput)
|
||||
- [`io/waitingForStandardInput`](#iowaitingforstandardinput)
|
||||
- [Errors](#errors)
|
||||
- [Library-Related Operations](#library-related-operations)
|
||||
- [`editions/listAvailable`](#editionslistavailable)
|
||||
- [`editions/resolve`](#editionsresolve)
|
||||
- [`editions/getProjectSettings`](#editionsgetprojectsettings)
|
||||
- [`editions/setProjectParentEdition`](#editionssetprojectparentedition)
|
||||
- [`editions/setProjectLocalLibrariesPreference`](#editionssetprojectlocallibrariespreference)
|
||||
- [`editions/listDefinedLibraries`](#editionslistdefinedlibraries)
|
||||
- [`library/listLocal`](#librarylistlocal)
|
||||
- [`library/create`](#librarycreate)
|
||||
- [`library/getMetadata`](#librarygetmetadata)
|
||||
- [`library/setMetadata`](#librarysetmetadata)
|
||||
- [`library/publish`](#librarypublish)
|
||||
- [`library/preinstall`](#librarypreinstall)
|
||||
- [Errors](#errors-74)
|
||||
- [`Error`](#error)
|
||||
- [`AccessDeniedError`](#accessdeniederror)
|
||||
- [`FileSystemError`](#filesystemerror)
|
||||
- [`ContentRootNotFoundError`](#contentrootnotfounderror)
|
||||
- [`FileNotFound`](#filenotfound)
|
||||
- [`FileExists`](#fileexists-1)
|
||||
- [`FileExists`](#fileexists)
|
||||
- [`OperationTimeoutError`](#operationtimeouterror)
|
||||
- [`NotDirectory`](#notdirectory)
|
||||
- [`NotFile`](#notfile)
|
||||
@ -179,6 +192,14 @@ transport formats, please look [here](./protocol-architecture).
|
||||
- [`ProjectNotFoundError`](#projectnotfounderror)
|
||||
- [`ModuleNameNotResolvedError`](#modulenamenotresolvederror)
|
||||
- [`SuggestionNotFoundError`](#suggestionnotfounderror)
|
||||
- [`EditionNotFoundError`](#editionnotfounderror)
|
||||
- [`LibraryAlreadyExists`](#libraryalreadyexists)
|
||||
- [`LibraryRepositoryAuthenticationError`](#libraryrepositoryauthenticationerror)
|
||||
- [`LibraryPublishError`](#librarypublisherror)
|
||||
- [`LibraryUploadError`](#libraryuploaderror)
|
||||
- [`LibraryDownloadError`](#librarydownloaderror)
|
||||
- [`LocalLibraryNotFound`](#locallibrarynotfound)
|
||||
- [`LibraryNotResolved`](#librarynotresolved)
|
||||
|
||||
<!-- /MarkdownTOC -->
|
||||
|
||||
@ -1212,6 +1233,62 @@ interface Custom {
|
||||
}
|
||||
```
|
||||
|
||||
### `LibraryEntry`
|
||||
|
||||
Represents a library available in a resolved edition.
|
||||
|
||||
```typescript
|
||||
interface LibraryEntry {
|
||||
namespace: String;
|
||||
name: String;
|
||||
version: LibraryVersion;
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
type LibraryVersion = LocalLibraryVersion | PublishedLibraryVersion;
|
||||
|
||||
/** A library version that references a version of the library published in some
|
||||
* repository.
|
||||
*/
|
||||
interface PublishedLibraryVersion {
|
||||
// A semver-compliant version of the library.
|
||||
version: String;
|
||||
|
||||
// URL to the repository that this library will be downloaded from.
|
||||
repositoryUrl: String;
|
||||
}
|
||||
|
||||
// A library version that references a locally editable version of the library.
|
||||
interface LocalLibraryVersion {}
|
||||
```
|
||||
|
||||
The local libraries do not have metadata associated with them by default, as for
|
||||
the published libraries, the canonical way to access the metadata is to download
|
||||
the manifest, as described in the
|
||||
[library repository structure](../libraries/repositories.md#libraries-repository).
|
||||
So the manifest URL can be found by combining the repository URL and library
|
||||
name and version: `<repositoryUrl>/<namespace>/<name>/<version>/manifest.yaml`.
|
||||
|
||||
### `EditionReference`
|
||||
|
||||
A reference to a specific edition.
|
||||
|
||||
Currently, it can either reference an edition by its name, or reference the
|
||||
edition associated with the currently open project.
|
||||
|
||||
```typescript
|
||||
type EditionReference = NamedEdition | CurrentProjectEdition;
|
||||
|
||||
// The edition associated with the current project, with all of its overrides.
|
||||
interface CurrentProjectEdition {}
|
||||
|
||||
// An edition stored under a given name.
|
||||
interface NamedEdition {
|
||||
editionName: String;
|
||||
}
|
||||
```
|
||||
|
||||
## Connection Management
|
||||
|
||||
In order to properly set-up and tear-down the language server connection, we
|
||||
@ -3918,6 +3995,429 @@ standard input.
|
||||
null;
|
||||
```
|
||||
|
||||
## Library-Related Operations
|
||||
|
||||
The library-related operations provide the Language Server with capabilities to
|
||||
check and modify project's edition settings, list editions published in a given
|
||||
edition, create local library projects which can be imported in the currently
|
||||
opened project and publish them.
|
||||
|
||||
### `editions/listAvailable`
|
||||
|
||||
Lists editions available on the system.
|
||||
|
||||
Moreover, if `update` is set to `true`, it will download any new editions from
|
||||
the repositories and include them in the result as well.
|
||||
|
||||
> Currently, if `update` was `true` but some downloads failed, the endpoint will
|
||||
> still return a success, just containing the editions that were already
|
||||
> available. In the future it should emit warnings using proper notification
|
||||
> channels.
|
||||
|
||||
The `update` field is optional and if it is not provided, it defaults to false.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
update?: Boolean;
|
||||
}
|
||||
```
|
||||
|
||||
#### Result
|
||||
|
||||
```typescript
|
||||
{
|
||||
editionNames: [String];
|
||||
}
|
||||
```
|
||||
|
||||
### `editions/resolve`
|
||||
|
||||
Resolves settings implied by the edition.
|
||||
|
||||
> Currently, it only resolves the engine version, as only it is needed, but
|
||||
> other settings may be added if necessary.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
edition: EditionReference;
|
||||
}
|
||||
```
|
||||
|
||||
#### Result
|
||||
|
||||
```typescript
|
||||
{
|
||||
engineVersion: String;
|
||||
}
|
||||
```
|
||||
|
||||
#### Errors
|
||||
|
||||
- [`EditionNotFoundError`](#editionnotfounderror) indicates that the requested
|
||||
edition, or some edition referenced in the ancestors of the edition being
|
||||
resolved, could not be found.
|
||||
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
||||
file-system error.
|
||||
|
||||
### `editions/getProjectSettings`
|
||||
|
||||
Returns the currently set edition-related settings of the project.
|
||||
|
||||
Currently, it only returns the parent edition and local library preference. Once
|
||||
more advanced edition settings are to be supported in the IDE, this endpoint
|
||||
will be extended.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
null;
|
||||
```
|
||||
|
||||
#### Result
|
||||
|
||||
```typescript
|
||||
{
|
||||
parentEdition?: String;
|
||||
preferLocalLibraries: Boolean;
|
||||
}
|
||||
```
|
||||
|
||||
The `parentEdition` may be missing if it is not set. It is possible to manually
|
||||
edit the `pacakge.yaml` and generate a valid edition config that does not
|
||||
specify a parent edition.
|
||||
|
||||
### `editions/setProjectParentEdition`
|
||||
|
||||
Sets the parent edition of the project to a specific edition.
|
||||
|
||||
This change may even change the version of the engine associated with the
|
||||
project, so for the changes to take effect, the language server may need to be
|
||||
restarted. The endpoint only modifies the `pacakge.yaml` file, which is
|
||||
preloaded in the Language Server, so it is IDE's responsibility to re-open the
|
||||
project.
|
||||
|
||||
It returns an optional field `needsRestart` which specifies whether the Language
|
||||
Server needs to be restarted for the change to take effect. If the field is
|
||||
missing, it should be treated as set to `false`. In the current version it is
|
||||
always set to `true`.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
newEditionName: String;
|
||||
}
|
||||
```
|
||||
|
||||
#### Result
|
||||
|
||||
```typescript
|
||||
{
|
||||
needsRestart?: Boolean;
|
||||
}
|
||||
```
|
||||
|
||||
#### Errors
|
||||
|
||||
- [`EditionNotFoundError`](#editionnotfounderror) indicates that the requested
|
||||
edition could not be found.
|
||||
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
||||
file-system error.
|
||||
|
||||
### `editions/setProjectLocalLibrariesPreference`
|
||||
|
||||
Sets the `prefer-local-libraries` setting of the project, which specifies if
|
||||
libraries from `ENSO_HOME/libraries` should take precedence over the ones
|
||||
defined in the edition.
|
||||
|
||||
> This may change which libraries should be loaded in the project. In the future
|
||||
> it may be possible that this reload could happen dynamically, however
|
||||
> currently, the language server needs to be restarted (in the same way as for
|
||||
> `editions/setProjectParentEdition`) for the changes to take effect.
|
||||
|
||||
It returns an optional field `needsRestart` which specifies whether the Language
|
||||
Server needs to be restarted for the change to take effect. If the field is
|
||||
missing, it should be treated as set to `false`. In the current version it is
|
||||
always set to `true`.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
preferLocalLibraries: Boolean;
|
||||
}
|
||||
```
|
||||
|
||||
#### Result
|
||||
|
||||
```typescript
|
||||
{
|
||||
needsRestart?: Boolean;
|
||||
}
|
||||
```
|
||||
|
||||
#### Errors
|
||||
|
||||
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
||||
file-system error.
|
||||
|
||||
### `editions/listDefinedLibraries`
|
||||
|
||||
Lists all libraries defined in an edition (or all of its parents).
|
||||
|
||||
This can be used to display which libraries can be downloaded / added to the
|
||||
project.
|
||||
|
||||
This does not include local libraries not defined explicitly in the project's
|
||||
edition, even if they can be resolved as per `prefer-local-libraries` setting.
|
||||
To get local libraries that are not directly referenced in the edition, use
|
||||
[`library/listLocal`](#librarylistlocal) instead.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
edition: EditionReference;
|
||||
}
|
||||
```
|
||||
|
||||
#### Result
|
||||
|
||||
```typescript
|
||||
{
|
||||
availableLibraries: [LibraryEntry];
|
||||
}
|
||||
```
|
||||
|
||||
#### Errors
|
||||
|
||||
- [`EditionNotFoundError`](#editionnotfounderror) indicates that the requested
|
||||
edition, or an edition referenced in one of its parents, could not be found.
|
||||
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
||||
file-system error.
|
||||
|
||||
### `library/listLocal`
|
||||
|
||||
Lists all local libraries available in the system.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
null;
|
||||
```
|
||||
|
||||
#### Result
|
||||
|
||||
```typescript
|
||||
{
|
||||
localLibraries: [LibraryEntry];
|
||||
}
|
||||
```
|
||||
|
||||
#### Errors
|
||||
|
||||
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
||||
file-system error.
|
||||
|
||||
### `library/create`
|
||||
|
||||
Creates a new project package, but placed not in the projects directory, but in
|
||||
the local libraries directory, so that other projects (including the current
|
||||
one) that can resolve local libraries will be able to import it.
|
||||
|
||||
The created library package inherits all edition settings from the current
|
||||
project.
|
||||
|
||||
The endpoint just returns an empty message at success. Once this operation
|
||||
finishes, the IDE can add the import `import <namespace>.<name>` to the open
|
||||
file which will import the newly created library (the IDE must also ensure that
|
||||
`prefer-local-libraries` is set to `true` or otherwise, it must add a proper
|
||||
override to its own edition file to see this local library). Once the import is
|
||||
added, the library will be loaded and its content root will be sent in a
|
||||
[`file/rootAdded`](#filerootadded) notification.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
namespace: String;
|
||||
name: String;
|
||||
authors: [String];
|
||||
maintainers: [String];
|
||||
license: String;
|
||||
}
|
||||
```
|
||||
|
||||
#### Result
|
||||
|
||||
```typescript
|
||||
null;
|
||||
```
|
||||
|
||||
#### Errors
|
||||
|
||||
- [`LibraryAlreadyExists`](#libraryalreadyexists) to signal that a library with
|
||||
the given namespace and name already exists.
|
||||
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
||||
file-system error.
|
||||
|
||||
### `library/getMetadata`
|
||||
|
||||
Gets metadata associated with a local library that will be used for publishing.
|
||||
|
||||
All returned fields are optional, as they may be missing.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
namespace: String;
|
||||
name: String;
|
||||
}
|
||||
```
|
||||
|
||||
#### Results
|
||||
|
||||
```typescript
|
||||
{
|
||||
description?: String;
|
||||
tagLine?: String;
|
||||
}
|
||||
```
|
||||
|
||||
#### Errors
|
||||
|
||||
- [`LocalLibraryNotFound`](#locallibrarynotfound) to signal that a local library
|
||||
with the given name does not exist on the local libraries path.
|
||||
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
||||
file-system error.
|
||||
|
||||
### `library/setMetadata`
|
||||
|
||||
Sets metadata associated with a local library that will be used for publishing.
|
||||
|
||||
All metadata fields are optional. If a field is not set in the parameters, it
|
||||
will be removed from the metadata (if it was present before).
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
namespace: String;
|
||||
name: String;
|
||||
description?: String;
|
||||
tagLine?: String;
|
||||
}
|
||||
```
|
||||
|
||||
#### Results
|
||||
|
||||
```typescript
|
||||
null;
|
||||
```
|
||||
|
||||
#### Errors
|
||||
|
||||
- [`LocalLibraryNotFound`](#locallibrarynotfound) to signal that a local library
|
||||
with the given name does not exist on the local libraries path.
|
||||
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
||||
file-system error.
|
||||
|
||||
### `library/publish`
|
||||
|
||||
Publishes a library located in the local libraries directory to the main Enso
|
||||
library repository.
|
||||
|
||||
If `bumpVersionAfterPublish` is set to true, after publishing the library, its
|
||||
version is bumped automatically, so that future publications will not clash
|
||||
versions. This is a temporary solution and in the longer-term it should be
|
||||
replaced with separate settings allowing to arbitrarily modify the library
|
||||
version from the IDE.
|
||||
|
||||
The metadata for publishing the library can be set with
|
||||
[`library/setMetadata`](#librarysetmetadata). If it was not set, the publish
|
||||
operation will still proceed, but that metadata will be missing.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
namespace: String;
|
||||
name: String;
|
||||
authToken: String;
|
||||
|
||||
bumpVersionAfterPublish?: Boolean;
|
||||
}
|
||||
```
|
||||
|
||||
#### Result
|
||||
|
||||
```typescript
|
||||
null;
|
||||
```
|
||||
|
||||
#### Errors
|
||||
|
||||
- [`LibraryPublishError`](#librarypublisherror) to signal that the server did
|
||||
not accept to publish the library (for example because a library with the same
|
||||
version already exists).
|
||||
- [`LibraryRepositoryAuthenticationError`](#libraryrepositoryauthenticationerror)
|
||||
to signal an authentication failure.
|
||||
- [`LibraryUploadError`](#libraryuploaderror) to signal that the upload
|
||||
operation has failed, for network-related reasons.
|
||||
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
||||
file-system error.
|
||||
|
||||
### `library/preinstall`
|
||||
|
||||
Ensures that the requested library and all of its (transitive) dependencies, at
|
||||
versions as resolved by the current project's edition, are downloaded.
|
||||
|
||||
Once this operation completes, the library import can be added to the project
|
||||
and it is guaranteed that (unless there were unexpected changes to the system,
|
||||
like files being manually deleted) no further downloads will be needed, so that
|
||||
the import should load quickly.
|
||||
|
||||
This can be used by the IDE to predownload the library that is about to be added
|
||||
to a project, to avoid freezing the compiler for the time the dependencies are
|
||||
being downloaded.
|
||||
|
||||
While this operation is in progress, multiple series of `task/*` notifications
|
||||
may be sent, indicating progress of particular components being downloaded and
|
||||
installed.
|
||||
|
||||
#### Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
namespace: String;
|
||||
name: String;
|
||||
}
|
||||
```
|
||||
|
||||
#### Result
|
||||
|
||||
```typescript
|
||||
null;
|
||||
```
|
||||
|
||||
#### Errors
|
||||
|
||||
- [`LibraryNotResolved`](#librarynotresolved) to signal that the requested
|
||||
library or one of its dependencies could not be resolved.
|
||||
- [`LibraryDownloadError`](#librarydownloaderror) to signal that the download
|
||||
operation has failed, for network-related reasons, or because the library was
|
||||
missing in the repository. The error includes the name and version of the
|
||||
library that failed to download - as when preinstalling a specific library the
|
||||
failure may be tied not to that library itself but also one of its
|
||||
dependencies.
|
||||
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
||||
file-system error.
|
||||
|
||||
## Errors
|
||||
|
||||
The language server component also has its own set of errors. This section is
|
||||
@ -4319,3 +4819,110 @@ Signals that the requested suggestion was not found.
|
||||
"message" : "Requested suggestion was not found"
|
||||
}
|
||||
```
|
||||
|
||||
### `EditionNotFoundError`
|
||||
|
||||
Signals that an edition could not be found.
|
||||
|
||||
Its payload includes the name of the edition that could not be found.
|
||||
|
||||
```typescript
|
||||
"error" : {
|
||||
"code" : 8001,
|
||||
"message" : "Edition [<name>] could not be found.",
|
||||
"payload" : {
|
||||
"editionName": "<name>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `LibraryAlreadyExists`
|
||||
|
||||
Signals that a local library with the specified namespace and name combination
|
||||
already exists, so it cannot be created again.
|
||||
|
||||
```typescript
|
||||
"error" : {
|
||||
"code" : 8002,
|
||||
"message" : "Library [<namespace>.<name>] already exists."
|
||||
}
|
||||
```
|
||||
|
||||
### `LibraryRepositoryAuthenticationError`
|
||||
|
||||
Signals that authentication to the library repository was declined.
|
||||
|
||||
```typescript
|
||||
"error" : {
|
||||
"code" : 8003,
|
||||
"message" : "Authentication failed: [message]"
|
||||
}
|
||||
```
|
||||
|
||||
### `LibraryPublishError`
|
||||
|
||||
Signals that a request to the library repository failed.
|
||||
|
||||
```typescript
|
||||
"error" : {
|
||||
"code" : 8004,
|
||||
"message" : "Could not publish the library: [message]"
|
||||
}
|
||||
```
|
||||
|
||||
### `LibraryUploadError`
|
||||
|
||||
Signals that uploading the library failed for network-related reasons.
|
||||
|
||||
```typescript
|
||||
"error" : {
|
||||
"code" : 8005,
|
||||
"message" : "Could not upload the library: [message]"
|
||||
}
|
||||
```
|
||||
|
||||
### `LibraryDownloadError`
|
||||
|
||||
Signals that downloading the library failed for network-related reasons or that
|
||||
it was not available in the repository.
|
||||
|
||||
```typescript
|
||||
"error" : {
|
||||
"code" : 8006,
|
||||
"message" : "Could not download the library: [message]",
|
||||
"payload" : {
|
||||
"namespace" : "<namespace>",
|
||||
"name" : "<name>",
|
||||
"version": "<version>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `LocalLibraryNotFound`
|
||||
|
||||
Signals that a local library with the specified namespace and name combination
|
||||
was not found on the local libraries path.
|
||||
|
||||
```typescript
|
||||
"error" : {
|
||||
"code" : 8007,
|
||||
"message" : "Local library [<namespace>.<name>] has not been found."
|
||||
}
|
||||
```
|
||||
|
||||
### `LibraryNotResolved`
|
||||
|
||||
Signals that a library could not be resolved - it was not defined in the edition
|
||||
and the settings did not allow to resolve local libraries or it did not exist
|
||||
there either.
|
||||
|
||||
```typescript
|
||||
"error" : {
|
||||
"code" : 8008,
|
||||
"message" : "Could not resolve [<namespace>.<name>].",
|
||||
"payload" : {
|
||||
"namespace" : "<namespace>",
|
||||
"name" : "<name>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user