Home Explore Blog CI



nushell

7th chunk of `contributor-book/plugin_protocol_reference.md`
3706c7a83c4d61cddc5f1568b6617705d667a18cc6cc6e730000000100000ff6
          "code": null,
          "url": null,
          "help": null,
          "inner": []
        }
      }
    }
  ]
}
```

#### `PipelineData` engine call response

A successful result with a Nu [`Value`](#value) or stream. The body is a [`PipelineDataHeader`](#pipelinedataheader).

Example:

```json
{
  "EngineCallResponse": [
    0,
    {
      "ListStream": {
        "id": 23,
        "span": {
          "start": 8081,
          "end": 8087
        }
      }
    }
  ]
}
```

#### `Config` engine call response

A successful result of a [`Config` engine call](#config-engine-call). The body is a [`Config`](#config).

Example:

```json
{
  "EngineCallResponse": [
    0,
    {
      "Config": {
        "external_completer": null,
        "filesize_metric": true,
        "table_mode": "Rounded",
        "table_move_header": false,
        ...
      }
    }
  ]
}
```

This example is abbreviated, as the [`Config`](#config) object is large and ever-changing.

#### `ValueMap` engine call response

A successful result for engine calls that produce plain maps, such as the [`GetEnvVars` engine call](#getenvvars-engine-call). The body is a map from strings to [`Value`s](#value).

Example:

```json
{
  "EngineCallResponse": [
    0,
    {
      "ValueMap": {
        "FOO": {
          "String": {
            "val": "bar",
            "span": {
              "start": 2020,
              "end": 2024
            }
          }
        }
      }
    }
  ]
}
```

#### `Identifier` engine call response

A successful result for engine calls that produce internal identifiers, such as [`FindDecl`](#finddecl-engine-call). The body is a `usize` (unsigned integer, platform pointer size).

Example:

```json
{
  "EngineCallResponse": [
    0,
    {
      "Identifier": 4221
    }
  ]
}
```

### `Signal`

The `Signal` message type is used to relay a signal from the engine to the plugin, allowing the plugin to respond to various system-level or user-initiated signals. The message body consists of a `SignalAction` enum, which currently supports the following variants:

- **`Interrupt`**: Sent when the engine receives an interrupt signal (such as Ctrl+C), to gracefully interrupt a plugin's operation.
- **`Reset`**: Sent when the engine’s `reset_signals` method is called, indicating that the plugin should reset its signal state.

Example:

```json
{
  "Signal": "Interrupt"
}
```

### `Goodbye`

Indicate that no further plugin calls are expected, and that the plugin **should** exit as soon as it is finished processing any in-progress plugin calls.

This message is not a map, it is just a bare string, as it takes no arguments.

Example:

```json
"Goodbye"
```

## Output messages

These are messages sent from the plugin to the engine. [`Hello`](#hello) and [`Stream messages`](#stream-messages) are also included.

### `CallResponse`

#### `Error` plugin call response

An error occurred while attempting to fulfill the request. The body is a [`LabeledError`](#labelederror).

It is strongly preferred to provide labeled messages whenever possible to let the user know where the problem might be in their script. If there is no more suitable span from a value that can be used, `head` from [`EvaluatedCall`](#evaluatedcall) is a good fallback.

Example:

```json
{
  "CallResponse": [
    0,
    {
      "Error": {
        "msg": "A really bad error occurred",
        "labels": [
          {
            "text": "I don't know, but it's over nine thousand!",
            "span": {
              "start": 9001,
              "end": 9007
            }
          }
        ],
        "code": "my_plugin::bad::really_bad",
        "url": "https://example.org/my_plugin/error/bad/really_bad.html",
        "help": "you can solve this by not doing the bad thing",
        "inner": [
          {
            "msg": "The bad thing"
          }
        ]
      }
    }
  ]
}
```

#### `Metadata` plugin call response

A successful response to a [`Metadata` plugin call](#metadata-plugin-call). The body contains fields that describe the plugin, none of which are required:

Title: Engine Call Responses: ValueMap, Identifier, Signal, Goodbye & CallResponse Details
Summary
This section details the remaining Engine Call Response types: `ValueMap` (for plain maps), and `Identifier` (for internal identifiers). It introduces the `Signal` message type, used to relay signals like `Interrupt` and `Reset` from the engine to the plugin. It also covers the `Goodbye` message, indicating no further plugin calls are expected. Lastly, it discusses the output message `CallResponse`, focusing on the `Error` plugin call response (an error with a `LabeledError`) and how to provide labeled messages, and briefly mentions the `Metadata` plugin call response.