Message Passing API

All messages are encoded in MessagePack, as an array with two elements.

The first element of the array is a code that designates the message’s type, encoded as an int. The second element of the array is the message body, encoded as a map.

Messages are passed between the client and the server. The client is the host language (for example, the Swift application when using pkl-swift). The server is the entity that provides controls for interacting with Pkl.

For example, in JSON representation:

[
  1,                           (1)
  { "someKey": "someValue" }   (2)
]

1	Code indicating message type
2	Message body

Message types

Client Message

A message passed from the client to the server.

Server Message

A message passed from the server to the client.

Request Message

A message sent with a requestId value. The requestId should be a unique number at the time of message send. The other side is expected to respond with a Response Message with the same requestId.

Response Message

A message that is the response to a Request Message. It contains the same requestId of the request message.

One Way Message

A fire-and-forget message where no response is expected.

Messages

All messages have their schema described in Pkl. A nullable type means that the property should be omitted (as opposed to the property’s value being nil).

Create Evaluator Request

Code: 0x20
Type: Client Request

Create an evaluator with the provided evaluator settings. Upon creating the evaluator, the server sends back a Create Evaluator Response message.

Schema:

/// A number identifying this request
requestId: Int

/// Regex patterns to determine which modules are allowed for import.
///
/// API version of the CLI's `--allowed-modules` flag
allowedModules: Listing<String>?

/// Regex patterns to dettermine which resources are allowed to be read.
///
/// API version of the CLI's `--allowed-resources` flag
allowedResources: Listing<String>?

/// Register client-side module readers.
clientModuleReaders: Listing<ClientModuleReader>?

/// Register client-side resource readers.
clientResourceReaders: Listing<ClientResourceReader>?

/// Directories, ZIP archives, or JAR archives
/// to search when resolving `modulepath:` URIs.
///
/// API version of the CLI's `--module-path` flag.
modulePaths: Listing<String>?

/// Environment variable to set.
///
/// API version of the CLI's `--env-var` flag.
env: Mapping<String, String>?

/// External properties to set.
///
/// API version of the CLI's `--properties` flag.
properties: Mapping<String, String>?

/// Duration, in seconds, after which evaluation of a source module will be timed out.
///
/// API version of the CLI's `--timeout` flag.
timeoutSeconds: Int?

/// Restricts access to file-based modules and resources to those located under the root directory.
rootDir: String?

/// The cache directory for storing packages.
cacheDir: String?

/// The format to generate.
///
/// This sets the `pkl.outputFormat` external property.
outputFormat: String?

/// The project dependency settings.
project: Project?

class ClientResourceReader {
  /// The URI scheme this reader is responsible for reading.
  scheme: String

  /// Tells whether the path part of ths URI has a
  /// [hier-part](https://datatracker.ietf.org/doc/html/rfc3986#section-3).
  ///
  /// An example of a hierarchical URI is `file:///path/to/my/file`, where
  /// `/path/to/my/file` designates a nested path through the `/` character.
  ///
  /// An example of a non-hierarchical URI is `pkl.base`, where the `base` does not denote
  /// any form of hierarchy.
  hasHierarchicalUris: Boolean

  /// Tells whether this reader supports globbing.
  isGlobbable: Boolean
}

class ClientModuleReader {
  /// The URI scheme this reader is responsible for reading.
  scheme: String

  /// Tells whether the path part of ths URI has a
  /// [hier-part](https://datatracker.ietf.org/doc/html/rfc3986#section-3).
  ///
  /// An example of a hierarchical URI is `file:///path/to/my/file`, where
  /// `/path/to/my/file` designates a nested path through the `/` character.
  ///
  /// An example of a non-hierarchical URI is `pkl.base`, where the `base` does not denote
  /// any form of hierarchy.
  hasHierarchicalUris: Boolean

  /// Tells whether this reader supports globbing.
  isGlobbable: Boolean

  /// Tells whether the module is local to the system.
  ///
  /// A local resource that [hasHierarchicalUris] supports triple-dot imports.
  isLocal: Boolean
}

class Project {
  type: "local"

  /// The canonical URI of this project's package
  packageUri: String?

  /// The URI pointing to the location of the project file.
  projectFileUri: String

  /// The dependencies of this project.
  dependencies: Mapping<String, Project|RemoteDependency>
}

class RemoteDependency {
  type: "remote"

  /// The canonical URI of this dependency
  packageUri: String?

  /// The checksums of this remote dependency
  checksums: Checksums?
}

class Checksums {
  /// The sha-256 checksum of this dependency's metadata.
  sha256: String
}

Example:

[
  0x20,
  {
    "requestId": 193501,
    "allowedModules": ["pkl:", "repl:"],
    "allowedResources": ["file:", "package:", "projectpackage:"]
  }
]

Create Evaluator Response

Code: 0x21
Type: Server Response

The response for a Create Evaluator Request. If the evaluator was created successfully, evaluatorId is set. Otherwise, error is set to the resulting error.

/// A number identifying this request
requestId: Int

/// A number identifying the created evaluator.
evaluatorId: Int?

/// A message detailing why the evaluator was not created.
error: String?

Close Evaluator

Code: 0x22
Type: Client One Way

Tells the Pkl server to close an evaluator, releasing any resources it may be holding.

/// A number identifying this evaluator.
evaluatorId: Int

Evaluate Request

Code: 0x23
Type: Client Request

Evaluate a module.

/// A number identifying this request
requestId: Int

/// A number identifying this evaluator.
evaluatorId: Int

/// The absolute URI of the module to be evaluated.
moduleUri: String

/// The module's contents.
///
/// If [null], Pkl will load the module at runtime.
moduleText: String?

/// The Pkl expression to be evaluated within the module.
///
/// If [null], evaluates the whole module.
expr: String?

Evaluate Response

Code: 0x24
Type: Server Response

The server’s response to Evaluate Request. If the evaluation is successful, the response is the Pkl value encoded in binary encoding.

/// The requestId of the Evaluate request
requestId: Int

/// A number identifying this evaluator.
evaluatorId: Int

/// The evaluation contents, if successful.
result: Binary? (1)

/// A message detailing why evaluation failed.
error: String?

typealias Binary = Any (1)

1	Pkl Binary Encoding in bin format (not expressable in Pkl)

Log

Code: 0x25
Type: Server One Way

Tells the client to emit a log message, during the execution of a Pkl program. A log can occur through a trace() expression, or through a warning (for example, when encountering a Deprecated value.)

/// A number identifying this evaluator.
evaluatorId: Int

/// A number identifying the log level.
///
/// - 0: trace
/// - 1: warn
level: Int(this == 0 || this == 1)

/// The message to be logged
message: String

/// A string representing the source location within Pkl code producing this log output.
frameUri: String

Read Resource Request

Code: 0x26
Type: Server Request

Read a resource at the given URI. This message occurs when a read expression (read/read?/read*) is encountered within a program, and its scheme matches a client resource reader.

/// A number identifying this request.
requestId: Int

/// A number identifying this evaluator.
evaluatorId: Int

/// The URI of the resource.
uri: String

Read Resource Response

Code: 0x27
Type: Client Response

The response to Read Resource Request. If successful, contents is set. Otherwise, error is set.

/// A number identifying this request.
requestId: Int

/// A number identifying this evaluator.
evaluatorId: Int

/// The contents of the resource.
contents: Binary? (1)

/// The description of the error that occured when reading this resource.
error: String?

typealias Binary = Any (1)

1	MessagePack’s bin format family (not expressable in Pkl)

Read Module Request

Code: 0x28
Type: Server Request

Read a module at the given URI. This message occurs during the evaluation of an import statement or expression (import/import*), when a scheme matches a client module reader.

/// A number identifying this request.
requestId: Int

/// A number identifying this evaluator.
evaluatorId: Int

/// The URI of the module.
uri: String

Read Module Response

Code: 0x29
Type: Client Response

The response to Read Module Request. If successful, contents is set. Otherwise, error is set.

/// A number identifying this request.
requestId: Int

/// A number identifying this evaluator.
evaluatorId: Int

/// The string contents of the module.
contents: String?

/// The description of the error that occured when reading this resource.
error: String?

List Resources Request

Code: 0x2a
Type: Server Request

List resources at the specified base path. This message occurs during the evaluation of a globbed read, when a scheme matches a client resource reader’s scheme.

If the resource reader does not have hierarchical URIs, dummy is used as the path, and the response is expected to contain all resource elements for that scheme.

/// A number identifying this request.
requestId: Int

/// A number identifying this evaluator.
evaluatorId: Int

/// The base URI to list resources.
uri: String

List Resources Response

Code: 0x2b
Type: Client Response

The response to List Resources Request. If successful, pathElements is set. Otherwise, error is set.

/// A number identifying this request.
requestId: Int

/// A number identifying this evaluator.
evaluatorId: Int

/// The elements at the provided base path.
pathElements: Listing<PathElement>?

/// The description of the error that occured when listing elements.
error: String?

class PathElement {
  /// The name of the element at this path
  name: String

  /// Tells whether the element is a directory.
  isDirectory: Boolean
}

List Modules Request

Code: 0x2c
Type: Server Request

List modules at the specified base path. This message occurs during the evaluation of a globbed import, when a scheme matches a client resource reader’s scheme.

If the module reader does not have hierarchical URIs, dummy is used as the path, and the response is expected to contain all module elements for that scheme.

/// A number identifying this request.
requestId: Int

/// A number identifying this evaluator.
evaluatorId: Int

/// The base URI to list modules.
uri: String

List Modules Response

Code: 0x2d
Type: Client Response

The response to List Modules Request. If successful, pathElements is set. Otherwise, error is set.

/// A number identifying this request.
requestId: Int

/// A number identifying this evaluator.
evaluatorId: Int

/// The elements at the provided base path.
pathElements: Listing<PathElement>?

/// The description of the error that occured when listing elements.
error: String?

class PathElement {
  /// The name of the element at this path
  name: String

  /// Tells whether the element is a directory.
  isDirectory: Boolean
}