> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Protocol Reference

> The gRPC protocol that all ubx engine plugins must implement.

The plugin protocol is defined in Protocol Buffers in the `ubx-plugin-protocol` repository. This page is the reference for the full message and service definitions.

## Service

```protobuf theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
service UbxPlugin {
  rpc Compile (CompileRequest)  returns (CompileResponse);
  rpc Plan    (PlanRequest)     returns (PlanResponse);
  rpc Apply   (ApplyRequest)    returns (stream ProgressEvent);
  rpc Destroy (DestroyRequest)  returns (stream ProgressEvent);
}
```

## StackMeta

Passed in every request:

```protobuf theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
message StackMeta {
  string name        = 1;   // stack name (directory name)
  string backend_uri = 2;   // backend URL (e.g. "s3://bucket/key")
}
```

## Compile

```protobuf theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
message CompileRequest {
  string    stack_dir         = 1;
  StackMeta meta              = 2;
  bytes     ir_json           = 3;
  string    ir_schema_version = 4;
}

message CompileResponse {
  string artifact_uri = 1;   // passed to Apply/Destroy
  string error        = 2;   // non-empty on failure
}
```

## Plan

```protobuf theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
message PlanRequest {
  string    stack_dir         = 1;
  StackMeta meta              = 2;
  bytes     ir_json           = 3;
  string    ir_schema_version = 4;
  repeated string targets     = 5;
}

message PlanResponse {
  string summary = 1;   // human-readable preview summary
  string error   = 2;
}
```

## Apply

```protobuf theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
message ApplyRequest {
  string   artifact_uri    = 1;
  StackMeta meta           = 2;
  repeated string targets  = 3;
}
```

Returns a stream of `ProgressEvent` messages until EOF.

## Destroy

```protobuf theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
message DestroyRequest {
  string    artifact_uri = 1;
  StackMeta meta         = 2;
}
```

Returns a stream of `ProgressEvent` messages until EOF.

## ProgressEvent

```protobuf theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
message ProgressEvent {
  oneof event {
    PhaseEvent      phase      = 1;
    ResourceEvent   resource   = 2;
    DiagnosticEvent diagnostic = 3;
    SummaryEvent    summary    = 4;
  }
}

message PhaseEvent {
  string name   = 1;
  string detail = 2;
}

message ResourceEvent {
  string            resource_type = 1;
  string            resource_name = 2;
  ResourceOperation operation     = 3;
  ResourceStatus    status        = 4;
  int64             elapsed_ms    = 5;
}

message DiagnosticEvent {
  DiagnosticSeverity severity = 1;
  string             message  = 2;
}

message SummaryEvent {
  bool   success     = 1;
  string error       = 2;
  int64  duration_ms = 3;
}
```

## Enums

```protobuf theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
enum ResourceOperation {
  RESOURCE_OPERATION_UNSPECIFIED = 0;
  RESOURCE_OPERATION_CREATE      = 1;
  RESOURCE_OPERATION_UPDATE      = 2;
  RESOURCE_OPERATION_DELETE      = 3;
  RESOURCE_OPERATION_SAME        = 4;
  RESOURCE_OPERATION_REPLACE     = 5;
}

enum ResourceStatus {
  RESOURCE_STATUS_UNSPECIFIED = 0;
  RESOURCE_STATUS_PENDING     = 1;
  RESOURCE_STATUS_COMPLETE    = 2;
  RESOURCE_STATUS_FAILED      = 3;
}

enum DiagnosticSeverity {
  DIAGNOSTIC_SEVERITY_UNSPECIFIED = 0;
  DIAGNOSTIC_SEVERITY_INFO        = 1;
  DIAGNOSTIC_SEVERITY_WARNING     = 2;
  DIAGNOSTIC_SEVERITY_ERROR       = 3;
}
```

## Launch handshake

1. ubx sets `UBX_PLUGIN_LAUNCH=1` in the plugin's environment
2. ubx launches the plugin binary
3. The plugin prints its gRPC port to stdout (e.g. `50051\n`)
4. ubx connects and calls RPCs
5. ubx closes the connection when done; the plugin exits

## IR JSON structure

The `ir_json` field in `CompileRequest` and `PlanRequest` contains a JSON-serialised `IRProgram`:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
{
  "stack_name": "networking",
  "engine":     "pulumi",
  "runtime":    "python",
  "inputs":     [{"name": "vpc_cidr", "type": "string", "default": {"kind": "literal", "value": "10.0.0.0/16"}}],
  "locals":     [{"name": "mylocals", "bindings": [{"key": "...", "value": {...}}]}],
  "resources":  [{"name": "vpc", "type_path": ["aws","ec2","Vpc"], "props": [...]}],
  "outputs":    [{"name": "vpc_id", "value": {"kind": "resource_ref", "binding": "vpc", "attr": "id"}}],
  "providers":  [{"name": "aws", "config": {...}}],
  "backend":    {"type": "s3", "bucket": "...", "key": "..."}
}
```

IR expression kinds: `literal`, `input_ref`, `locals_ref`, `resource_ref`, `cross_stack`, `remote_ref`, `binary`, `unary`, `list`, `object`, `fstring`, `heredoc`, `match`, `ternary`, `call`, `data_ref`, `secret_ref`.