Plugin Protocol Reference

service UbxPlugin {
  rpc Compile (CompileRequest)  returns (CompileResponse);
  rpc Plan    (PlanRequest)     returns (PlanResponse);
  rpc Apply   (ApplyRequest)    returns (stream ProgressEvent);
  rpc Destroy (DestroyRequest)  returns (stream ProgressEvent);
}

message StackMeta {
  string name        = 1;   // stack name (directory name)
  string backend_uri = 2;   // backend URL (e.g. "s3://bucket/key")
}

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
}

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;
}

message ApplyRequest {
  string   artifact_uri    = 1;
  StackMeta meta           = 2;
  repeated string targets  = 3;
}

message DestroyRequest {
  string    artifact_uri = 1;
  StackMeta meta         = 2;
}

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;
}

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;
}

{
  "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": "..."}
}