Files
archie/proto/controlplane/v1/controlplane.proto
T
sam f61e680d8c feat(controlplane): expose resource history so edits can be reviewed and rolled back
resource_history has carried a row per change since the control plane landed
(value, version, actor, source, request ID, both versions, timestamp), but
nothing could read it. The audit trail existed and was invisible, and the PRD's
"shows failed changes and can correct or roll them back" had nothing to stand
on.

Restoring is deliberately not a command of its own. A revision carries the
value it held, so putting one back is an ordinary replace against the version
currently stored: the restore lands in the same history as every other edit,
under the same optimistic concurrency, instead of rewriting the past.

The revision value crosses the HTTP boundary as raw JSON rather than the base64
a proto bytes field renders as, because the dashboard sends it straight back as
the replace payload.

ResourceStore is exported from the controlplane package and the State Store
composition asserts against it, replacing the inline anonymous interface that
had started to drift from the real requirement.
2026-09-21 09:11:17 +10:00

81 lines
2.2 KiB
Protocol Buffer

syntax = "proto3";
package controlplane.v1;
import "google/protobuf/timestamp.proto";
service ControlPlaneService {
rpc Catalog(CatalogRequest) returns (CatalogResponse);
rpc Query(QueryRequest) returns (QueryResponse);
rpc History(HistoryRequest) returns (HistoryResponse);
rpc Command(CommandRequest) returns (CommandResponse);
rpc Watch(WatchRequest) returns (stream WatchResponse);
}
message ResourceDescriptor {
string kind = 1;
string title = 2;
string schema_json = 3;
repeated string commands = 4;
// ApplyMode is "live", "restart-required", or "domain-managed".
string apply_mode = 5;
// QueryService and command_service identify an existing domain API when
// the resource is not stored as a generic JSON document.
string query_service = 6;
string command_service = 7;
// DefaultsJson is the factory value a client can restore this resource to.
// Empty when the resource has no shipped default.
string defaults_json = 8;
}
message CatalogRequest {}
message CatalogResponse { repeated ResourceDescriptor resources = 1; }
message Resource {
string kind = 1;
int64 version = 2;
bytes value_json = 3;
google.protobuf.Timestamp updated_at = 4;
}
message QueryRequest { string kind = 1; }
message QueryResponse { Resource resource = 1; }
// Revision is one entry of a resource's audit trail: the value that version
// held, and who changed it from where.
message Revision {
int64 version = 1;
bytes value_json = 2;
string actor = 3;
string source = 4;
string request_id = 5;
google.protobuf.Timestamp at = 6;
}
message HistoryRequest {
string kind = 1;
// Limit caps the revisions returned, newest first. Zero means the server's
// own default.
int32 limit = 2;
}
message HistoryResponse { repeated Revision revisions = 1; }
message CommandRequest {
string kind = 1;
string command = 2;
bytes value_json = 3;
int64 expected_version = 4;
string request_id = 5;
// Actor and source are supplied by a trusted service adapter, never copied
// from browser/request JSON.
string actor = 6;
string source = 7;
}
message CommandResponse { Resource resource = 1; }
message WatchRequest {
string kind = 1;
int64 after_version = 2;
}
message WatchResponse {
Resource resource = 1;
string error = 2;
}