DartPad Worker Protocol

The bin/shared_worker.dart program is intended to run as a SharedWorker in the browser. The client can communicate with the worker over the MessagePort created when connecting to the SharedWorker. This document describes the protocol for communication over this port.

In the description below the worker is bin/shared_worker.dart and client is the web page that connected to the SharedWorker.

Concepts:

• Session, when a client connects to the worker, a session is created. Sessions do share the same file-system and thread. But are otherwise independent, and should be using differnet parts of the virtual file-system.
• Workspace, a workspace is a folder and associated resources for running language-servers and compiling source code.
• Language-server, a process running within a workspace that provides a language-server-protocol server for Dart.
• Hot-reload compiler, a process running with a workspace that faciliates incremental compilation of a single entry-point.

JSON-RPC 2.0

Communication with the worker uses JSON-RPC 2.0. Communication over the MessagePort takes place using raw JSON objects (utilizing the browser's structured clone algorithm), not JSON-encoded strings.

The following sections outline which methods are offered by the worker...

JSON-RPC 2.0 requests are usually on the form:

{
  "jsonrpc": "2.0",
  "method": "<name-of-method>",
  "params": {
    // parameters for the method
  },
  "id": 42 // unique ID per request, omitted for notifications!
}

If the id property is omitted, then the message is said to be a notification and no response will be sent. For requests the id must be unique and must be used by the client to find the matching response for the request.

Response objects are usually on the form:

{
  "jsonrpc": "2.0",
  "result": {
    // result values from the method
  },
  "id": 42 // ID from the request
}

If an error occured when handling a request, then an error will be returned. Errors will never be returned for notifications, since notifications don't carry an id property, they never produce a response or an error.

Errors are usually on the form:

{
  "jsonrpc": "2.0",
  "error": {
    "code": 1000, // Integer error code (negative numbers are reserved)
    "message": "<human readable message>",
    "data": {
      // Arbitrary data associated from the error handler.
    }
  },
  "id": 42 // ID from the request
}

When sending requests and notifications is possible to batch multiple messages into a single message by sending an array of requests and notifications.

For further details about JSON-RPC 2.0, refer to the specification.

Server Methods and Notifications

Methods are prefixed based on what objects they operate on. Thus, all methods prefixed workspace/ require a workspaceId parameter.

Method createWorkspace

Creates workspace with a dedicated workspaceFolder.

Params:

{} // No parameters!

Result:

{
  // The workspaceId is a unique number identifying the workspace created
  "workspaceId": 42,
  // Folder on the shared file-system dedicated to this workspace
  "workspaceFolder": "file:///workspace/pad_42/",
}

Method workspace/dispose

Deletes the workspace and all associated resources.

Params:

{
  "workspaceId": 42,
}

Result:

{} // empty result

Method workspace/writeFileFromText

Write a text string to a file as UTF-8. Parent directories will be automatically created.

Params:

{
  "workspaceId": 42,
  // URI of the file that you want to write.
  // Can be absolute file:// or relative to workspaceFolder
  "uri": "bin/hello.dart",
  // Text that should be written to the file.
  // This will be written as UTF-8.
  "text": "void main() => print('hello world');",
}

Result:

{} // empty result

Method workspace/writeFileFromBytes

Params:

{
  "workspaceId": 42,
  "uri": "bin/hello.dart",
  // Bytes that should be written to the file as base64
  "base64": "<base64-encoded bytes>",
}

Result:

{} // empty result

Method workspace/readFileAsText

Params:

{
  "workspaceId": 42,
  "uri": "bin/hello.dart",
}

Result:

{
  "text": "<contents of the file as UTF-8>"
}

Method workspace/readFileAsBytes

Params:

{
  "workspaceId": 42,
  "uri": "bin/hello.dart",
}

Result:

{
  "base64": "<bytes from the file encoded as base64>"
}

Method workspace/deleteFileSystemEntity

Params:

{
  "workspaceId": 42,
  // URI of the file or folder that you want to delete.
  "uri": "bin/hello.dart",
}

Result:

{} // empty result

Method workspace/stat

Get information about a file or folder.

Params:

{
  "workspaceId": 42,
  "uri": "bin/hello.dart",
}

Result:

{
  // Type of the entity: "file", "folder" or "other"
  "type": "file" | "folder" | "other",
  // Size in bytes (only for files)
  "size": 1024
}

Method workspace/createFolder

Params:

{
  "workspaceId": 42,
  "uri": "lib",
}

Result:

{} // empty result

Method workspace/listDirectory

Params:

{
  "workspaceId": 42,
  "uri": "lib",
  // Whether to list recursively (default: false)
  "recursive": true,
  // Whether to ignore hidden files (starting with .) (default: false)
  "ignoreHidden": true
}

Result:

{
  // List of entries. Paths are relative to the uri listed.
  "entries": [
    {"path": "main.dart", "type": "file"},
    {"path": "src", "type": "folder"}
  ]
}

Method workspace/importTarArchive

Import a tar archive (uncompressed) into the workspace.

Params:

{
  "workspaceId": 42,
  // Path where to extract the archive.
  "uri": ".",
  // Base64 encoded tar archive.
  "base64": "<base64-encoded-tar>"
}

Result:

{} // empty result

Method workspace/exportTarArchive

Export a directory as a tar archive (uncompressed).

Params:

{
  "workspaceId": 42,
  // Directory to export.
  "uri": "."
}

Result:

{
  // Base64 encoded tar archive.
  "base64": "<base64-encoded-tar>"
}

Method workspace/pub

Runs pub in the specified directory.

Params:

{
  "workspaceId": 42,
  // Directory to run pub in.
  "uri": ".",
  // Command to run.
  "command": "get" | "add" | "downgrade" | "outdated" | "upgrade" | "remove" | "unpack",
  // Arguments to pass to the pub command (optional)
  "args": ["--dry-run"]
}

Result:

{
  "log": "<output from pub get>",
}

Method workspace/startHotReloadCompiler

Start a hot-reload compiler for uri.

Params:

{
  "workspaceId": 42,
  "uri": "bin/hello.dart",
}

Result:

{
  // identifier for the hot-reload compiler just started
  "hotReloadCompilerId": 67,
}

Method workspace/hotReloadCompiler/compile

Run the hot-reload compiler for the uri it was started with. Returns code and compiledLibraryUris, which must be supplied to the hot-reload method as librariesToReload when hot-reloading.

Params:

{
  "workspaceId": 42,
  "hotReloadCompilerId": 67,
}

Result:

{
  // Code is `null` if compilation failed!
  "code": "<javascript code>" || null,
  "compiledLibraryUris": ["package:myapp/myapp.dart", ...],
  "log": "<log lines>",
}

Method workspace/hotReloadCompiler/close

Close the hot-reload compiler, releasing resources (memory) held.

Params:

{
  "workspaceId": 42,
  "hotReloadCompilerId": 67,
}

Result:

{} // empty result

Method workspace/startLanguageServer

Start a language-server.

Params:

{
  "workspaceId": 42,
}

Result:

{
  "languageServerId": 36, // identifier for the language-server just started
}

Method workspace/languageServer/message

Sends an LSP message to a running language server.

Params:

{
  "workspaceId": 42,
  "languageServerId": 36,
  "message": {
    // JSON-RPC 2.0 message for the language-server
    "jsonrpc": "2.0",
    "method": "...",
    "params": {...},
    "id": ...,
  },
}

Result:

{} // empty result

Method workspace/languageServer/stop

Params:

{
  "workspaceId": 42,
  "languageServerId": 36,
}

Result:

{} // empty result

Client Notifications

Notification workspace/languageServer/message

Sent by the worker when the language server produces a message.

Params:

{
  "workspaceId": 42,
  "languageServerId": 36,
  "message": {
    // JSON-RPC 2.0 message from the language-server
  }
}

Notification workspace/languageServer/exited

Sent by the worker when a language server process terminates.

Params:

{
  "workspaceId": 42,
  "languageServerId": 36
}

Error codes

Errors returned by the worker use the following codes.