Home Explore Blog CI



nushell

13th chunk of `contributor-book/plugin_protocol_reference.md`
cf8ad81ad1619fa478e0e17d42d6f694b0c9052906b795ab0000000100001069
          "positional": [
            {
              "String": {
                "val": "0.1.2",
                "span": {
                  "start": 40407,
                  "end": 40415
                }
              }
            }
          ],
          "named": [
            [
              "major",
              {
                "Bool": {
                  "val": true,
                  "span": {
                    "start": 40404,
                    "end": 40406
                  }
                }
              }
            ]
          ]
        },
        "input": {
          "Value": {
            "Int": {
              "val": 400,
              "span": {
                "start": 40390,
                "end": 40393
              }
            }
          }
        },
        "redirect_stdout": true,
        "redirect_stderr": false
      }
    }
  }
}
```

### `Option`

Sets options that affect how the engine treats the plugin. No response is expected for this message.

#### `GcDisabled` option

Set to `true` to stop the plugin from being automatically garbage collected, or `false` to enable it again.

Example:

```json
{
  "Option": {
    "GcDisabled": true
  }
}
```

## Stream messages

Streams can be sent by both the plugin and the engine. The agent that is sending the stream is known as the _producer_, and the agent that receives the stream is known as the _consumer_.

All stream messages reference a stream ID. This identifier is an integer starting at zero and is specified by the producer in the message that described what the stream would be used for: for example, [`Call`](#call) or [`CallResponse`](#callresponse). A producer **should not** reuse identifiers it has used once before. The most obvious implementation is sequential, where each new stream gets an incremented number. It is not necessary for stream IDs to be totally unique across both the plugin and the engine: stream `0` from the plugin and stream `0` from the engine are different streams.

### `Data`

This message is sent from producer to consumer. The body is a 2-tuple (array) of (`id`, `data`).

The `data` is either a `List` map for a list stream, in which case the body is the [`Value`](#value) to be sent, or `Raw` for a raw stream, in which case the body is either an `Ok` map with a byte buffer, or an `Err` map with a [`LabeledError`](#labelederror).

Examples:

```json
{
  "Data": [
    0,
    {
      "List": {
        "String": {
          "val": "Hello, world!",
          "span": {
            "start": 40000,
            "end": 40015
          }
        }
      }
    }
  ]
}
```

```json
{
  "Data": [
    0,
    {
      "Raw": {
        "Ok": [72, 101, 108, 108, 111, 44, 32, 119, 111, 114, 108, 100, 33]
      }
    }
  ]
}
```

```json
{
  "Data": [
    0,
    {
      "Raw": {
        "Err": {
          "IOError": {
            "msg": "disconnected"
          }
        }
      }
    }
  ]
}
```

### `End`

This message is sent from producer to consumer. The body is a single value, the `id`.

**Must** be sent at the end of a stream by the producer. The producer **must not** send any more [`Data`](#data) messages after the end of the stream.

The consumer **must** send [`Drop`](#drop) in reply unless the stream ended because the consumer chose to drop the stream.

Example:

```json
{
  "End": 0
}
```

### `Ack`

This message is sent from consumer to producer. The body is a single value, the `id`.

Sent by the consumer in reply to each [`Data`](#data) message, indicating that the consumer has finished processing that message. `Ack` is used for flow control. If a consumer does not need to process a stream immediately, or is having trouble keeping up, it **should not** send `Ack` messages until it is ready to process more `Data`.

Example:

```json
{
  "Ack": 0
}
```

### `Drop`

This message is sent from consumer to producer. The body is a single value, the `id`.

Sent by the consumer to indicate disinterest in further messages from a stream. The producer **may** send additional [`Data`](#data) messages after `Drop` has been received, but **should** make an effort to stop sending messages and [`End`](#end) the stream as soon as possible.

Title: Engine Options and Stream Messages: Controlling Plugin Behavior and Data Transfer
Summary
This section details engine options like `GcDisabled` for managing garbage collection and the stream messaging system for data transfer between plugins and the engine. It describes `Data` messages for sending either list or raw data, `End` messages to signal the end of a stream, `Ack` messages for flow control, and `Drop` messages to indicate disinterest in further stream data.