152 lines
4.5 KiB
Protocol Buffer
152 lines
4.5 KiB
Protocol Buffer
syntax = "proto3";
|
|
|
|
package connector.v1;
|
|
|
|
import "google/protobuf/timestamp.proto";
|
|
|
|
// ConnectorService is the surface every connector extension serves: it
|
|
// declares what it hears and does, turns verified payloads into typed events,
|
|
// resolves and runs actions, and answers lookups. The host invokes everything
|
|
// by name; payloads are JSON validated against the declared schemas.
|
|
service ConnectorService {
|
|
// Configure hands the connector its operator settings and resolved secrets.
|
|
// The host calls it once after launch and again when settings change.
|
|
rpc Configure(ConfigureRequest) returns (ConfigureResponse);
|
|
// Describe declares the connector's event types, actions and lookups.
|
|
rpc Describe(DescribeRequest) returns (DescribeResponse);
|
|
// Parse turns a payload the host has already verified into typed events.
|
|
rpc Parse(ParseRequest) returns (ParseResponse);
|
|
// Resolve works out the structured target and the effect of one concrete
|
|
// action before it is judged. The same action can have different effects on
|
|
// different targets.
|
|
rpc Resolve(ResolveRequest) returns (ResolveResponse);
|
|
// Invoke runs one judged action. The connector honours the idempotency key
|
|
// and returns the digest of what it actually executed.
|
|
rpc Invoke(InvokeRequest) returns (InvokeResponse);
|
|
// Lookup answers a read-only question. Lookups change nothing and run no
|
|
// guards; a lookup that finds nothing says so.
|
|
rpc Lookup(LookupRequest) returns (LookupResponse);
|
|
}
|
|
|
|
message ConfigureRequest {
|
|
map<string, string> settings = 1;
|
|
map<string, string> secrets = 2;
|
|
}
|
|
message ConfigureResponse {}
|
|
|
|
message DescribeRequest {}
|
|
message DescribeResponse {
|
|
// contract is the contract version the connector speaks, "v1".
|
|
string contract = 1;
|
|
repeated EventType events = 2;
|
|
repeated ActionType actions = 3;
|
|
repeated LookupType lookups = 4;
|
|
}
|
|
|
|
message EventType {
|
|
string name = 1;
|
|
string description = 2;
|
|
// schema is the JSON Schema of the event's fields.
|
|
bytes schema = 3;
|
|
}
|
|
|
|
message ActionType {
|
|
string name = 1;
|
|
string description = 2;
|
|
// input_schema is the JSON Schema of the action's input.
|
|
bytes input_schema = 3;
|
|
// effect is the static declaration; Resolve refines it per action.
|
|
Effect effect = 4;
|
|
// idempotent declares that the connector honours idempotency keys. A
|
|
// connector that declares external effects without it has its actions
|
|
// refused.
|
|
bool idempotent = 5;
|
|
}
|
|
|
|
message LookupType {
|
|
string name = 1;
|
|
string description = 2;
|
|
bytes input_schema = 3;
|
|
}
|
|
|
|
enum Reversibility {
|
|
REVERSIBILITY_UNSPECIFIED = 0;
|
|
// REVERSIBILITY_UNDONE_AUTOMATICALLY can be reversed without help.
|
|
REVERSIBILITY_UNDONE_AUTOMATICALLY = 1;
|
|
// REVERSIBILITY_RECOVERABLE can be recovered from a snapshot, or touches
|
|
// only a disposable target.
|
|
REVERSIBILITY_RECOVERABLE = 2;
|
|
REVERSIBILITY_IRREVERSIBLE = 3;
|
|
}
|
|
|
|
message Effect {
|
|
bool read_only = 1;
|
|
Reversibility reversibility = 2;
|
|
// summary says in plain words what the action does, for example "delete
|
|
// files older than 24h under /tmp/runner".
|
|
string summary = 3;
|
|
}
|
|
|
|
// Target is what an action acts on. Connector, action, kind and environment
|
|
// together are the action class.
|
|
message Target {
|
|
string kind = 1;
|
|
string id = 2;
|
|
string environment = 3;
|
|
bool disposable = 4;
|
|
}
|
|
|
|
message ParseRequest {
|
|
bytes body = 1;
|
|
map<string, string> headers = 2;
|
|
}
|
|
message ParseResponse {
|
|
repeated Event events = 1;
|
|
}
|
|
|
|
message Event {
|
|
string type = 1;
|
|
// source_event_id is unique per source; a re-delivery repeats it.
|
|
string source_event_id = 2;
|
|
// fields is the event's JSON, matching its type's schema.
|
|
bytes fields = 3;
|
|
// link_key links this event to an earlier one it resolves or follows, such
|
|
// as Alertmanager's fingerprint.
|
|
string link_key = 4;
|
|
google.protobuf.Timestamp occurred_at = 5;
|
|
}
|
|
|
|
message ResolveRequest {
|
|
string action = 1;
|
|
bytes input = 2;
|
|
}
|
|
message ResolveResponse {
|
|
Target target = 1;
|
|
Effect effect = 2;
|
|
}
|
|
|
|
message InvokeRequest {
|
|
string action = 1;
|
|
bytes input = 2;
|
|
string idempotency_key = 3;
|
|
// digest is the host's digest of the judged action.
|
|
string digest = 4;
|
|
}
|
|
message InvokeResponse {
|
|
bytes output = 1;
|
|
// executed_digest is the connector's digest of what it ran. A mismatch is a
|
|
// finding and tightens the action class.
|
|
string executed_digest = 2;
|
|
// outcome_unknown says the connector can't confirm what its effect did.
|
|
bool outcome_unknown = 3;
|
|
}
|
|
|
|
message LookupRequest {
|
|
string lookup = 1;
|
|
bytes input = 2;
|
|
}
|
|
message LookupResponse {
|
|
bytes output = 1;
|
|
bool found = 2;
|
|
}
|