246 lines
7.8 KiB
Protocol Buffer
246 lines
7.8 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);
|
|
// Deliver sends a message or record to people or a system of record. A
|
|
// delivery is never offered to an agent: hard rules apply to it, guards
|
|
// don't. The host retries a failed delivery, so a connector should make a
|
|
// repeat with the same idempotency key harmless where its service allows.
|
|
// A connector returns InvalidArgument, FailedPrecondition, PermissionDenied
|
|
// or NotFound when the service rejects the delivery permanently: the host
|
|
// records the reason and stops retrying. Any other status is retried.
|
|
rpc Deliver(DeliverRequest) returns (DeliverResponse);
|
|
// Listen streams the events of a source the connector holds its own
|
|
// connection to, such as a chat long poll, from cursor on. Each response
|
|
// carries the cursor to resume after its events, which the host keeps only
|
|
// once those events are stored.
|
|
rpc Listen(ListenRequest) returns (stream ListenResponse);
|
|
// TargetFacts answers what the connector's system of record knows about a
|
|
// target, such as who owns it, at the moment an action on it is judged. The
|
|
// host asks only connectors that declare target_facts, and never stores the
|
|
// answer.
|
|
rpc TargetFacts(TargetFactsRequest) returns (TargetFactsResponse);
|
|
}
|
|
|
|
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;
|
|
repeated DeliveryType deliveries = 5;
|
|
// listens says the connector serves Listen.
|
|
bool listens = 6;
|
|
// target_facts says the connector serves TargetFacts.
|
|
bool target_facts = 7;
|
|
// settings are the values an operator enters for the connector to run,
|
|
// which the dashboard renders as a form.
|
|
repeated Setting settings = 8;
|
|
// version is the connector's own release.
|
|
string version = 9;
|
|
}
|
|
|
|
// Setting is one value an operator enters for an extension to run.
|
|
message Setting {
|
|
string key = 1;
|
|
string label = 2;
|
|
string description = 3;
|
|
// secret says the value is a secret reference, never the secret.
|
|
bool secret = 4;
|
|
bool required = 5;
|
|
// type decides how the value is entered and checked; unspecified is a
|
|
// string.
|
|
SettingType type = 6;
|
|
// options are the allowed values of a select setting.
|
|
repeated string options = 7;
|
|
}
|
|
|
|
enum SettingType {
|
|
SETTING_TYPE_UNSPECIFIED = 0;
|
|
SETTING_TYPE_STRING = 1;
|
|
SETTING_TYPE_NUMBER = 2;
|
|
SETTING_TYPE_BOOLEAN = 3;
|
|
SETTING_TYPE_DURATION = 4;
|
|
SETTING_TYPE_LIST = 5;
|
|
SETTING_TYPE_SELECT = 6;
|
|
SETTING_TYPE_TEXT = 7;
|
|
}
|
|
|
|
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 DeliveryType {
|
|
string name = 1;
|
|
string description = 2;
|
|
bytes input_schema = 3;
|
|
}
|
|
|
|
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;
|
|
}
|
|
|
|
message DeliverRequest {
|
|
string delivery = 1;
|
|
bytes input = 2;
|
|
string idempotency_key = 3;
|
|
}
|
|
message DeliverResponse {
|
|
// external_id is what the service called what was delivered, for linking.
|
|
string external_id = 1;
|
|
}
|
|
|
|
message TargetFactsRequest {
|
|
Target target = 1;
|
|
}
|
|
message TargetFactsResponse {
|
|
// found is false when the connector has no record of the target.
|
|
bool found = 1;
|
|
// owner_identity is who answers for the target, as an identity on a channel
|
|
// or system, such as "servicenow:jdoe" or "email:jo@example.com".
|
|
string owner_identity = 2;
|
|
// data_class names what the target holds, such as "customer" or "temp".
|
|
string data_class = 3;
|
|
// count is how many things the target stands for, zero when unknown.
|
|
int32 count = 4;
|
|
}
|
|
|
|
message ListenRequest {
|
|
// cursor is the last cursor the host stored, empty from the start.
|
|
string cursor = 1;
|
|
}
|
|
message ListenResponse {
|
|
repeated Event events = 1;
|
|
string cursor = 2;
|
|
}
|