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

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