Files
archie/proto/connector/v1/connector.proto
T

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