// SPDX-License-Identifier: Apache-2.0
// Shared messages of the Kyvernon native API (v1).
//
// Conventions:
// * Object ids are MoRef-compatible strings ("vm-42", "host-7").
// * Timestamps are RFC 3339 strings in UTC with microsecond precision.
// * Typed record bodies travel as JSON (`*_json` fields) in v1; the schemas
//   are published in docs/api/openapi.yaml. Dedicated protobuf messages exist
//   where the operation itself is typed (power operations, tasks, agent).
syntax = "proto3";

package kyvernon.v1;

// Store-maintained metadata of every record.
message RecordMeta {
  // Id of the object (`vm-12`, `host-3`).
  string id = 1;
  // UUID of the object, stable for its lifetime.
  string uuid = 2;
  // Id of the parent in the inventory tree; empty for a root.
  string parent = 3;
  // Name of the object.
  string name = 4;
  // Store version of the last change; the expected version of a compare-and-set update.
  uint64 version = 5;
  // Store version that created the object.
  uint64 created_version = 6;
  // Creation time, RFC 3339.
  string created_at = 7;
  // Time of the last change, RFC 3339.
  string updated_at = 8;
}

// A record with its JSON body.
message Object {
  // Identity, place and versions of the object.
  RecordMeta meta = 1;
  // Object kind (for example `VirtualMachine`).
  string kind = 2;
  // The kind-specific body as JSON, the same shape as in the REST API.
  string data_json = 3;
}

// Pagination request; `after` is the id to resume after.
message PageRequest {
  // Most items in one answer; 0 means the server default.
  uint32 limit = 1;
  // Cursor: the `next` of the previous page; empty for the first page.
  string after = 2;
}

// Pagination response.
message PageInfo {
  // Store version the page was read at.
  uint64 version = 1;
  // Cursor of the next page; empty on the last page.
  string next = 2;
}

// Error details attached to gRPC status (also the REST envelope body).
message ErrorDetail {
  // Error code (`NOT_FOUND`, `FAILED_PRECONDITION`, ...).
  string code = 1;
  // English developer message.
  string message = 2;
  // Message id the console localises (`error.not_found`); empty when there is none.
  string key = 3;
  // Arguments of the message id.
  map<string, string> details = 4;
  // Correlation id of the request (the `x-request-id` metadata, or one the server chose).
  string correlation_id = 5;
}

// Reference to a task created by a long-running operation.
message TaskRef {
  // Id of the task to poll or wait for.
  string task_id = 1;
}

// No fields.
message Empty {}