From 58858f0d921c2ed65de3da0ec3dcd45af6a12d99 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 15 Nov 2026 17:24:31 +1100 Subject: [PATCH] feat(connectors): the connector contract and its confined extension host (#1979) --- .golangci.yml | 9 +- .../contracts/connector/v1/connector.pb.go | 1317 +++++++++++++++++ .../connector/v1/connector_grpc.pb.go | 343 +++++ modules/connectors/connector.go | 296 ++++ modules/connectors/connector_test.go | 96 ++ modules/connectors/connectors.go | 93 ++ modules/connectors/internal/egress/policy.go | 88 ++ modules/connectors/internal/egress/tunnel.go | 148 ++ .../connectors/internal/egress/upstream.go | 54 + .../connectors/internal/host/confine_linux.go | 168 +++ .../connectors/internal/host/confine_other.go | 20 + modules/connectors/internal/host/gate.go | 48 + modules/connectors/internal/host/hclog.go | 119 ++ modules/connectors/internal/host/host.go | 198 +++ proto/connector/v1/connector.proto | 151 ++ 15 files changed, 3147 insertions(+), 1 deletion(-) create mode 100644 internal/contracts/connector/v1/connector.pb.go create mode 100644 internal/contracts/connector/v1/connector_grpc.pb.go create mode 100644 modules/connectors/connector.go create mode 100644 modules/connectors/connector_test.go create mode 100644 modules/connectors/connectors.go create mode 100644 modules/connectors/internal/egress/policy.go create mode 100644 modules/connectors/internal/egress/tunnel.go create mode 100644 modules/connectors/internal/egress/upstream.go create mode 100644 modules/connectors/internal/host/confine_linux.go create mode 100644 modules/connectors/internal/host/confine_other.go create mode 100644 modules/connectors/internal/host/gate.go create mode 100644 modules/connectors/internal/host/hclog.go create mode 100644 modules/connectors/internal/host/host.go create mode 100644 proto/connector/v1/connector.proto diff --git a/.golangci.yml b/.golangci.yml index 1a5dc5df8..de0e38220 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -113,7 +113,14 @@ linters: - {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "old service code; move what you need into a module"} - {pkg: "github.com/samcharles93/archie-core/internal/domain", desc: "old domain code; move what you need into a module"} - {pkg: "github.com/samcharles93/archie-core/internal/infrastructure", desc: "old infrastructure; move what you need into a module"} - - {pkg: "github.com/samcharles93/archie-core/internal/contracts", desc: "internal service contracts are being deleted"} + - {pkg: "github.com/samcharles93/archie-core/internal/contracts/state", desc: "an internal service contract being deleted"} + - {pkg: "github.com/samcharles93/archie-core/internal/contracts/gateway", desc: "an internal service contract being deleted"} + - {pkg: "github.com/samcharles93/archie-core/internal/contracts/daemon", desc: "an internal service contract being deleted"} + - {pkg: "github.com/samcharles93/archie-core/internal/contracts/controlplane", desc: "an internal service contract being deleted"} + - {pkg: "github.com/samcharles93/archie-core/internal/contracts/messaging", desc: "an internal service contract being deleted"} + - {pkg: "github.com/samcharles93/archie-core/internal/contracts/logging", desc: "an internal service contract being deleted"} + - {pkg: "github.com/samcharles93/archie-core/internal/contracts/forge", desc: "an internal service contract being deleted"} + - {pkg: "github.com/samcharles93/archie-core/internal/contracts/channel", desc: "an internal service contract being deleted"} - {pkg: "github.com/samcharles93/archie-core/internal/config", desc: "the single binary has its own bootstrap config"} - {pkg: "github.com/nats-io", desc: "the single binary has no message bus"} shared: diff --git a/internal/contracts/connector/v1/connector.pb.go b/internal/contracts/connector/v1/connector.pb.go new file mode 100644 index 000000000..4f98de133 --- /dev/null +++ b/internal/contracts/connector/v1/connector.pb.go @@ -0,0 +1,1317 @@ +// Code generated by protoc-gen-go. DO NOT EDIT. +// versions: +// protoc-gen-go v1.36.11 +// protoc (unknown) +// source: connector/v1/connector.proto + +package connectorv1 + +import ( + protoreflect "google.golang.org/protobuf/reflect/protoreflect" + protoimpl "google.golang.org/protobuf/runtime/protoimpl" + timestamppb "google.golang.org/protobuf/types/known/timestamppb" + reflect "reflect" + sync "sync" + unsafe "unsafe" +) + +const ( + // Verify that this generated code is sufficiently up-to-date. + _ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion) + // Verify that runtime/protoimpl is sufficiently up-to-date. + _ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20) +) + +type Reversibility int32 + +const ( + Reversibility_REVERSIBILITY_UNSPECIFIED Reversibility = 0 + // REVERSIBILITY_UNDONE_AUTOMATICALLY can be reversed without help. + Reversibility_REVERSIBILITY_UNDONE_AUTOMATICALLY Reversibility = 1 + // REVERSIBILITY_RECOVERABLE can be recovered from a snapshot, or touches + // only a disposable target. + Reversibility_REVERSIBILITY_RECOVERABLE Reversibility = 2 + Reversibility_REVERSIBILITY_IRREVERSIBLE Reversibility = 3 +) + +// Enum value maps for Reversibility. +var ( + Reversibility_name = map[int32]string{ + 0: "REVERSIBILITY_UNSPECIFIED", + 1: "REVERSIBILITY_UNDONE_AUTOMATICALLY", + 2: "REVERSIBILITY_RECOVERABLE", + 3: "REVERSIBILITY_IRREVERSIBLE", + } + Reversibility_value = map[string]int32{ + "REVERSIBILITY_UNSPECIFIED": 0, + "REVERSIBILITY_UNDONE_AUTOMATICALLY": 1, + "REVERSIBILITY_RECOVERABLE": 2, + "REVERSIBILITY_IRREVERSIBLE": 3, + } +) + +func (x Reversibility) Enum() *Reversibility { + p := new(Reversibility) + *p = x + return p +} + +func (x Reversibility) String() string { + return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x)) +} + +func (Reversibility) Descriptor() protoreflect.EnumDescriptor { + return file_connector_v1_connector_proto_enumTypes[0].Descriptor() +} + +func (Reversibility) Type() protoreflect.EnumType { + return &file_connector_v1_connector_proto_enumTypes[0] +} + +func (x Reversibility) Number() protoreflect.EnumNumber { + return protoreflect.EnumNumber(x) +} + +// Deprecated: Use Reversibility.Descriptor instead. +func (Reversibility) EnumDescriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{0} +} + +type ConfigureRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + Settings map[string]string `protobuf:"bytes,1,rep,name=settings,proto3" json:"settings,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"` + Secrets map[string]string `protobuf:"bytes,2,rep,name=secrets,proto3" json:"secrets,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ConfigureRequest) Reset() { + *x = ConfigureRequest{} + mi := &file_connector_v1_connector_proto_msgTypes[0] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ConfigureRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ConfigureRequest) ProtoMessage() {} + +func (x *ConfigureRequest) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[0] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ConfigureRequest.ProtoReflect.Descriptor instead. +func (*ConfigureRequest) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{0} +} + +func (x *ConfigureRequest) GetSettings() map[string]string { + if x != nil { + return x.Settings + } + return nil +} + +func (x *ConfigureRequest) GetSecrets() map[string]string { + if x != nil { + return x.Secrets + } + return nil +} + +type ConfigureResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ConfigureResponse) Reset() { + *x = ConfigureResponse{} + mi := &file_connector_v1_connector_proto_msgTypes[1] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ConfigureResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ConfigureResponse) ProtoMessage() {} + +func (x *ConfigureResponse) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[1] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ConfigureResponse.ProtoReflect.Descriptor instead. +func (*ConfigureResponse) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{1} +} + +type DescribeRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *DescribeRequest) Reset() { + *x = DescribeRequest{} + mi := &file_connector_v1_connector_proto_msgTypes[2] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *DescribeRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*DescribeRequest) ProtoMessage() {} + +func (x *DescribeRequest) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[2] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use DescribeRequest.ProtoReflect.Descriptor instead. +func (*DescribeRequest) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{2} +} + +type DescribeResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + // contract is the contract version the connector speaks, "v1". + Contract string `protobuf:"bytes,1,opt,name=contract,proto3" json:"contract,omitempty"` + Events []*EventType `protobuf:"bytes,2,rep,name=events,proto3" json:"events,omitempty"` + Actions []*ActionType `protobuf:"bytes,3,rep,name=actions,proto3" json:"actions,omitempty"` + Lookups []*LookupType `protobuf:"bytes,4,rep,name=lookups,proto3" json:"lookups,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *DescribeResponse) Reset() { + *x = DescribeResponse{} + mi := &file_connector_v1_connector_proto_msgTypes[3] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *DescribeResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*DescribeResponse) ProtoMessage() {} + +func (x *DescribeResponse) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[3] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use DescribeResponse.ProtoReflect.Descriptor instead. +func (*DescribeResponse) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{3} +} + +func (x *DescribeResponse) GetContract() string { + if x != nil { + return x.Contract + } + return "" +} + +func (x *DescribeResponse) GetEvents() []*EventType { + if x != nil { + return x.Events + } + return nil +} + +func (x *DescribeResponse) GetActions() []*ActionType { + if x != nil { + return x.Actions + } + return nil +} + +func (x *DescribeResponse) GetLookups() []*LookupType { + if x != nil { + return x.Lookups + } + return nil +} + +type EventType struct { + state protoimpl.MessageState `protogen:"open.v1"` + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"` + // schema is the JSON Schema of the event's fields. + Schema []byte `protobuf:"bytes,3,opt,name=schema,proto3" json:"schema,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *EventType) Reset() { + *x = EventType{} + mi := &file_connector_v1_connector_proto_msgTypes[4] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *EventType) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*EventType) ProtoMessage() {} + +func (x *EventType) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[4] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use EventType.ProtoReflect.Descriptor instead. +func (*EventType) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{4} +} + +func (x *EventType) GetName() string { + if x != nil { + return x.Name + } + return "" +} + +func (x *EventType) GetDescription() string { + if x != nil { + return x.Description + } + return "" +} + +func (x *EventType) GetSchema() []byte { + if x != nil { + return x.Schema + } + return nil +} + +type ActionType struct { + state protoimpl.MessageState `protogen:"open.v1"` + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"` + // input_schema is the JSON Schema of the action's input. + InputSchema []byte `protobuf:"bytes,3,opt,name=input_schema,json=inputSchema,proto3" json:"input_schema,omitempty"` + // effect is the static declaration; Resolve refines it per action. + Effect *Effect `protobuf:"bytes,4,opt,name=effect,proto3" json:"effect,omitempty"` + // idempotent declares that the connector honours idempotency keys. A + // connector that declares external effects without it has its actions + // refused. + Idempotent bool `protobuf:"varint,5,opt,name=idempotent,proto3" json:"idempotent,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ActionType) Reset() { + *x = ActionType{} + mi := &file_connector_v1_connector_proto_msgTypes[5] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ActionType) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ActionType) ProtoMessage() {} + +func (x *ActionType) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[5] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ActionType.ProtoReflect.Descriptor instead. +func (*ActionType) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{5} +} + +func (x *ActionType) GetName() string { + if x != nil { + return x.Name + } + return "" +} + +func (x *ActionType) GetDescription() string { + if x != nil { + return x.Description + } + return "" +} + +func (x *ActionType) GetInputSchema() []byte { + if x != nil { + return x.InputSchema + } + return nil +} + +func (x *ActionType) GetEffect() *Effect { + if x != nil { + return x.Effect + } + return nil +} + +func (x *ActionType) GetIdempotent() bool { + if x != nil { + return x.Idempotent + } + return false +} + +type LookupType struct { + state protoimpl.MessageState `protogen:"open.v1"` + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"` + InputSchema []byte `protobuf:"bytes,3,opt,name=input_schema,json=inputSchema,proto3" json:"input_schema,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *LookupType) Reset() { + *x = LookupType{} + mi := &file_connector_v1_connector_proto_msgTypes[6] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *LookupType) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*LookupType) ProtoMessage() {} + +func (x *LookupType) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[6] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use LookupType.ProtoReflect.Descriptor instead. +func (*LookupType) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{6} +} + +func (x *LookupType) GetName() string { + if x != nil { + return x.Name + } + return "" +} + +func (x *LookupType) GetDescription() string { + if x != nil { + return x.Description + } + return "" +} + +func (x *LookupType) GetInputSchema() []byte { + if x != nil { + return x.InputSchema + } + return nil +} + +type Effect struct { + state protoimpl.MessageState `protogen:"open.v1"` + ReadOnly bool `protobuf:"varint,1,opt,name=read_only,json=readOnly,proto3" json:"read_only,omitempty"` + Reversibility Reversibility `protobuf:"varint,2,opt,name=reversibility,proto3,enum=connector.v1.Reversibility" json:"reversibility,omitempty"` + // summary says in plain words what the action does, for example "delete + // files older than 24h under /tmp/runner". + Summary string `protobuf:"bytes,3,opt,name=summary,proto3" json:"summary,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *Effect) Reset() { + *x = Effect{} + mi := &file_connector_v1_connector_proto_msgTypes[7] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *Effect) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*Effect) ProtoMessage() {} + +func (x *Effect) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[7] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use Effect.ProtoReflect.Descriptor instead. +func (*Effect) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{7} +} + +func (x *Effect) GetReadOnly() bool { + if x != nil { + return x.ReadOnly + } + return false +} + +func (x *Effect) GetReversibility() Reversibility { + if x != nil { + return x.Reversibility + } + return Reversibility_REVERSIBILITY_UNSPECIFIED +} + +func (x *Effect) GetSummary() string { + if x != nil { + return x.Summary + } + return "" +} + +// Target is what an action acts on. Connector, action, kind and environment +// together are the action class. +type Target struct { + state protoimpl.MessageState `protogen:"open.v1"` + Kind string `protobuf:"bytes,1,opt,name=kind,proto3" json:"kind,omitempty"` + Id string `protobuf:"bytes,2,opt,name=id,proto3" json:"id,omitempty"` + Environment string `protobuf:"bytes,3,opt,name=environment,proto3" json:"environment,omitempty"` + Disposable bool `protobuf:"varint,4,opt,name=disposable,proto3" json:"disposable,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *Target) Reset() { + *x = Target{} + mi := &file_connector_v1_connector_proto_msgTypes[8] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *Target) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*Target) ProtoMessage() {} + +func (x *Target) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[8] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use Target.ProtoReflect.Descriptor instead. +func (*Target) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{8} +} + +func (x *Target) GetKind() string { + if x != nil { + return x.Kind + } + return "" +} + +func (x *Target) GetId() string { + if x != nil { + return x.Id + } + return "" +} + +func (x *Target) GetEnvironment() string { + if x != nil { + return x.Environment + } + return "" +} + +func (x *Target) GetDisposable() bool { + if x != nil { + return x.Disposable + } + return false +} + +type ParseRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + Body []byte `protobuf:"bytes,1,opt,name=body,proto3" json:"body,omitempty"` + Headers map[string]string `protobuf:"bytes,2,rep,name=headers,proto3" json:"headers,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ParseRequest) Reset() { + *x = ParseRequest{} + mi := &file_connector_v1_connector_proto_msgTypes[9] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ParseRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ParseRequest) ProtoMessage() {} + +func (x *ParseRequest) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[9] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ParseRequest.ProtoReflect.Descriptor instead. +func (*ParseRequest) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{9} +} + +func (x *ParseRequest) GetBody() []byte { + if x != nil { + return x.Body + } + return nil +} + +func (x *ParseRequest) GetHeaders() map[string]string { + if x != nil { + return x.Headers + } + return nil +} + +type ParseResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + Events []*Event `protobuf:"bytes,1,rep,name=events,proto3" json:"events,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ParseResponse) Reset() { + *x = ParseResponse{} + mi := &file_connector_v1_connector_proto_msgTypes[10] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ParseResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ParseResponse) ProtoMessage() {} + +func (x *ParseResponse) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[10] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ParseResponse.ProtoReflect.Descriptor instead. +func (*ParseResponse) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{10} +} + +func (x *ParseResponse) GetEvents() []*Event { + if x != nil { + return x.Events + } + return nil +} + +type Event struct { + state protoimpl.MessageState `protogen:"open.v1"` + Type string `protobuf:"bytes,1,opt,name=type,proto3" json:"type,omitempty"` + // source_event_id is unique per source; a re-delivery repeats it. + SourceEventId string `protobuf:"bytes,2,opt,name=source_event_id,json=sourceEventId,proto3" json:"source_event_id,omitempty"` + // fields is the event's JSON, matching its type's schema. + Fields []byte `protobuf:"bytes,3,opt,name=fields,proto3" json:"fields,omitempty"` + // link_key links this event to an earlier one it resolves or follows, such + // as Alertmanager's fingerprint. + LinkKey string `protobuf:"bytes,4,opt,name=link_key,json=linkKey,proto3" json:"link_key,omitempty"` + OccurredAt *timestamppb.Timestamp `protobuf:"bytes,5,opt,name=occurred_at,json=occurredAt,proto3" json:"occurred_at,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *Event) Reset() { + *x = Event{} + mi := &file_connector_v1_connector_proto_msgTypes[11] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *Event) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*Event) ProtoMessage() {} + +func (x *Event) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[11] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use Event.ProtoReflect.Descriptor instead. +func (*Event) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{11} +} + +func (x *Event) GetType() string { + if x != nil { + return x.Type + } + return "" +} + +func (x *Event) GetSourceEventId() string { + if x != nil { + return x.SourceEventId + } + return "" +} + +func (x *Event) GetFields() []byte { + if x != nil { + return x.Fields + } + return nil +} + +func (x *Event) GetLinkKey() string { + if x != nil { + return x.LinkKey + } + return "" +} + +func (x *Event) GetOccurredAt() *timestamppb.Timestamp { + if x != nil { + return x.OccurredAt + } + return nil +} + +type ResolveRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + Action string `protobuf:"bytes,1,opt,name=action,proto3" json:"action,omitempty"` + Input []byte `protobuf:"bytes,2,opt,name=input,proto3" json:"input,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ResolveRequest) Reset() { + *x = ResolveRequest{} + mi := &file_connector_v1_connector_proto_msgTypes[12] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ResolveRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ResolveRequest) ProtoMessage() {} + +func (x *ResolveRequest) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[12] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ResolveRequest.ProtoReflect.Descriptor instead. +func (*ResolveRequest) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{12} +} + +func (x *ResolveRequest) GetAction() string { + if x != nil { + return x.Action + } + return "" +} + +func (x *ResolveRequest) GetInput() []byte { + if x != nil { + return x.Input + } + return nil +} + +type ResolveResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + Target *Target `protobuf:"bytes,1,opt,name=target,proto3" json:"target,omitempty"` + Effect *Effect `protobuf:"bytes,2,opt,name=effect,proto3" json:"effect,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ResolveResponse) Reset() { + *x = ResolveResponse{} + mi := &file_connector_v1_connector_proto_msgTypes[13] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ResolveResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ResolveResponse) ProtoMessage() {} + +func (x *ResolveResponse) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[13] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ResolveResponse.ProtoReflect.Descriptor instead. +func (*ResolveResponse) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{13} +} + +func (x *ResolveResponse) GetTarget() *Target { + if x != nil { + return x.Target + } + return nil +} + +func (x *ResolveResponse) GetEffect() *Effect { + if x != nil { + return x.Effect + } + return nil +} + +type InvokeRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + Action string `protobuf:"bytes,1,opt,name=action,proto3" json:"action,omitempty"` + Input []byte `protobuf:"bytes,2,opt,name=input,proto3" json:"input,omitempty"` + IdempotencyKey string `protobuf:"bytes,3,opt,name=idempotency_key,json=idempotencyKey,proto3" json:"idempotency_key,omitempty"` + // digest is the host's digest of the judged action. + Digest string `protobuf:"bytes,4,opt,name=digest,proto3" json:"digest,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *InvokeRequest) Reset() { + *x = InvokeRequest{} + mi := &file_connector_v1_connector_proto_msgTypes[14] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *InvokeRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*InvokeRequest) ProtoMessage() {} + +func (x *InvokeRequest) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[14] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use InvokeRequest.ProtoReflect.Descriptor instead. +func (*InvokeRequest) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{14} +} + +func (x *InvokeRequest) GetAction() string { + if x != nil { + return x.Action + } + return "" +} + +func (x *InvokeRequest) GetInput() []byte { + if x != nil { + return x.Input + } + return nil +} + +func (x *InvokeRequest) GetIdempotencyKey() string { + if x != nil { + return x.IdempotencyKey + } + return "" +} + +func (x *InvokeRequest) GetDigest() string { + if x != nil { + return x.Digest + } + return "" +} + +type InvokeResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + Output []byte `protobuf:"bytes,1,opt,name=output,proto3" json:"output,omitempty"` + // executed_digest is the connector's digest of what it ran. A mismatch is a + // finding and tightens the action class. + ExecutedDigest string `protobuf:"bytes,2,opt,name=executed_digest,json=executedDigest,proto3" json:"executed_digest,omitempty"` + // outcome_unknown says the connector can't confirm what its effect did. + OutcomeUnknown bool `protobuf:"varint,3,opt,name=outcome_unknown,json=outcomeUnknown,proto3" json:"outcome_unknown,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *InvokeResponse) Reset() { + *x = InvokeResponse{} + mi := &file_connector_v1_connector_proto_msgTypes[15] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *InvokeResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*InvokeResponse) ProtoMessage() {} + +func (x *InvokeResponse) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[15] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use InvokeResponse.ProtoReflect.Descriptor instead. +func (*InvokeResponse) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{15} +} + +func (x *InvokeResponse) GetOutput() []byte { + if x != nil { + return x.Output + } + return nil +} + +func (x *InvokeResponse) GetExecutedDigest() string { + if x != nil { + return x.ExecutedDigest + } + return "" +} + +func (x *InvokeResponse) GetOutcomeUnknown() bool { + if x != nil { + return x.OutcomeUnknown + } + return false +} + +type LookupRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + Lookup string `protobuf:"bytes,1,opt,name=lookup,proto3" json:"lookup,omitempty"` + Input []byte `protobuf:"bytes,2,opt,name=input,proto3" json:"input,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *LookupRequest) Reset() { + *x = LookupRequest{} + mi := &file_connector_v1_connector_proto_msgTypes[16] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *LookupRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*LookupRequest) ProtoMessage() {} + +func (x *LookupRequest) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[16] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use LookupRequest.ProtoReflect.Descriptor instead. +func (*LookupRequest) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{16} +} + +func (x *LookupRequest) GetLookup() string { + if x != nil { + return x.Lookup + } + return "" +} + +func (x *LookupRequest) GetInput() []byte { + if x != nil { + return x.Input + } + return nil +} + +type LookupResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + Output []byte `protobuf:"bytes,1,opt,name=output,proto3" json:"output,omitempty"` + Found bool `protobuf:"varint,2,opt,name=found,proto3" json:"found,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *LookupResponse) Reset() { + *x = LookupResponse{} + mi := &file_connector_v1_connector_proto_msgTypes[17] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *LookupResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*LookupResponse) ProtoMessage() {} + +func (x *LookupResponse) ProtoReflect() protoreflect.Message { + mi := &file_connector_v1_connector_proto_msgTypes[17] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use LookupResponse.ProtoReflect.Descriptor instead. +func (*LookupResponse) Descriptor() ([]byte, []int) { + return file_connector_v1_connector_proto_rawDescGZIP(), []int{17} +} + +func (x *LookupResponse) GetOutput() []byte { + if x != nil { + return x.Output + } + return nil +} + +func (x *LookupResponse) GetFound() bool { + if x != nil { + return x.Found + } + return false +} + +var File_connector_v1_connector_proto protoreflect.FileDescriptor + +const file_connector_v1_connector_proto_rawDesc = "" + + "\n" + + "\x1cconnector/v1/connector.proto\x12\fconnector.v1\x1a\x1fgoogle/protobuf/timestamp.proto\"\x9c\x02\n" + + "\x10ConfigureRequest\x12H\n" + + "\bsettings\x18\x01 \x03(\v2,.connector.v1.ConfigureRequest.SettingsEntryR\bsettings\x12E\n" + + "\asecrets\x18\x02 \x03(\v2+.connector.v1.ConfigureRequest.SecretsEntryR\asecrets\x1a;\n" + + "\rSettingsEntry\x12\x10\n" + + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + + "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\x1a:\n" + + "\fSecretsEntry\x12\x10\n" + + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + + "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\"\x13\n" + + "\x11ConfigureResponse\"\x11\n" + + "\x0fDescribeRequest\"\xc7\x01\n" + + "\x10DescribeResponse\x12\x1a\n" + + "\bcontract\x18\x01 \x01(\tR\bcontract\x12/\n" + + "\x06events\x18\x02 \x03(\v2\x17.connector.v1.EventTypeR\x06events\x122\n" + + "\aactions\x18\x03 \x03(\v2\x18.connector.v1.ActionTypeR\aactions\x122\n" + + "\alookups\x18\x04 \x03(\v2\x18.connector.v1.LookupTypeR\alookups\"Y\n" + + "\tEventType\x12\x12\n" + + "\x04name\x18\x01 \x01(\tR\x04name\x12 \n" + + "\vdescription\x18\x02 \x01(\tR\vdescription\x12\x16\n" + + "\x06schema\x18\x03 \x01(\fR\x06schema\"\xb3\x01\n" + + "\n" + + "ActionType\x12\x12\n" + + "\x04name\x18\x01 \x01(\tR\x04name\x12 \n" + + "\vdescription\x18\x02 \x01(\tR\vdescription\x12!\n" + + "\finput_schema\x18\x03 \x01(\fR\vinputSchema\x12,\n" + + "\x06effect\x18\x04 \x01(\v2\x14.connector.v1.EffectR\x06effect\x12\x1e\n" + + "\n" + + "idempotent\x18\x05 \x01(\bR\n" + + "idempotent\"e\n" + + "\n" + + "LookupType\x12\x12\n" + + "\x04name\x18\x01 \x01(\tR\x04name\x12 \n" + + "\vdescription\x18\x02 \x01(\tR\vdescription\x12!\n" + + "\finput_schema\x18\x03 \x01(\fR\vinputSchema\"\x82\x01\n" + + "\x06Effect\x12\x1b\n" + + "\tread_only\x18\x01 \x01(\bR\breadOnly\x12A\n" + + "\rreversibility\x18\x02 \x01(\x0e2\x1b.connector.v1.ReversibilityR\rreversibility\x12\x18\n" + + "\asummary\x18\x03 \x01(\tR\asummary\"n\n" + + "\x06Target\x12\x12\n" + + "\x04kind\x18\x01 \x01(\tR\x04kind\x12\x0e\n" + + "\x02id\x18\x02 \x01(\tR\x02id\x12 \n" + + "\venvironment\x18\x03 \x01(\tR\venvironment\x12\x1e\n" + + "\n" + + "disposable\x18\x04 \x01(\bR\n" + + "disposable\"\xa1\x01\n" + + "\fParseRequest\x12\x12\n" + + "\x04body\x18\x01 \x01(\fR\x04body\x12A\n" + + "\aheaders\x18\x02 \x03(\v2'.connector.v1.ParseRequest.HeadersEntryR\aheaders\x1a:\n" + + "\fHeadersEntry\x12\x10\n" + + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + + "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\"<\n" + + "\rParseResponse\x12+\n" + + "\x06events\x18\x01 \x03(\v2\x13.connector.v1.EventR\x06events\"\xb3\x01\n" + + "\x05Event\x12\x12\n" + + "\x04type\x18\x01 \x01(\tR\x04type\x12&\n" + + "\x0fsource_event_id\x18\x02 \x01(\tR\rsourceEventId\x12\x16\n" + + "\x06fields\x18\x03 \x01(\fR\x06fields\x12\x19\n" + + "\blink_key\x18\x04 \x01(\tR\alinkKey\x12;\n" + + "\voccurred_at\x18\x05 \x01(\v2\x1a.google.protobuf.TimestampR\n" + + "occurredAt\">\n" + + "\x0eResolveRequest\x12\x16\n" + + "\x06action\x18\x01 \x01(\tR\x06action\x12\x14\n" + + "\x05input\x18\x02 \x01(\fR\x05input\"m\n" + + "\x0fResolveResponse\x12,\n" + + "\x06target\x18\x01 \x01(\v2\x14.connector.v1.TargetR\x06target\x12,\n" + + "\x06effect\x18\x02 \x01(\v2\x14.connector.v1.EffectR\x06effect\"~\n" + + "\rInvokeRequest\x12\x16\n" + + "\x06action\x18\x01 \x01(\tR\x06action\x12\x14\n" + + "\x05input\x18\x02 \x01(\fR\x05input\x12'\n" + + "\x0fidempotency_key\x18\x03 \x01(\tR\x0eidempotencyKey\x12\x16\n" + + "\x06digest\x18\x04 \x01(\tR\x06digest\"z\n" + + "\x0eInvokeResponse\x12\x16\n" + + "\x06output\x18\x01 \x01(\fR\x06output\x12'\n" + + "\x0fexecuted_digest\x18\x02 \x01(\tR\x0eexecutedDigest\x12'\n" + + "\x0foutcome_unknown\x18\x03 \x01(\bR\x0eoutcomeUnknown\"=\n" + + "\rLookupRequest\x12\x16\n" + + "\x06lookup\x18\x01 \x01(\tR\x06lookup\x12\x14\n" + + "\x05input\x18\x02 \x01(\fR\x05input\">\n" + + "\x0eLookupResponse\x12\x16\n" + + "\x06output\x18\x01 \x01(\fR\x06output\x12\x14\n" + + "\x05found\x18\x02 \x01(\bR\x05found*\x95\x01\n" + + "\rReversibility\x12\x1d\n" + + "\x19REVERSIBILITY_UNSPECIFIED\x10\x00\x12&\n" + + "\"REVERSIBILITY_UNDONE_AUTOMATICALLY\x10\x01\x12\x1d\n" + + "\x19REVERSIBILITY_RECOVERABLE\x10\x02\x12\x1e\n" + + "\x1aREVERSIBILITY_IRREVERSIBLE\x10\x032\xbf\x03\n" + + "\x10ConnectorService\x12L\n" + + "\tConfigure\x12\x1e.connector.v1.ConfigureRequest\x1a\x1f.connector.v1.ConfigureResponse\x12I\n" + + "\bDescribe\x12\x1d.connector.v1.DescribeRequest\x1a\x1e.connector.v1.DescribeResponse\x12@\n" + + "\x05Parse\x12\x1a.connector.v1.ParseRequest\x1a\x1b.connector.v1.ParseResponse\x12F\n" + + "\aResolve\x12\x1c.connector.v1.ResolveRequest\x1a\x1d.connector.v1.ResolveResponse\x12C\n" + + "\x06Invoke\x12\x1b.connector.v1.InvokeRequest\x1a\x1c.connector.v1.InvokeResponse\x12C\n" + + "\x06Lookup\x12\x1b.connector.v1.LookupRequest\x1a\x1c.connector.v1.LookupResponseB\xc4\x01\n" + + "\x10com.connector.v1B\x0eConnectorProtoP\x01ZOgithub.com/samcharles93/archie-core/internal/contracts/connector/v1;connectorv1\xa2\x02\x03CXX\xaa\x02\fConnector.V1\xca\x02\fConnector\\V1\xe2\x02\x18Connector\\V1\\GPBMetadata\xea\x02\rConnector::V1b\x06proto3" + +var ( + file_connector_v1_connector_proto_rawDescOnce sync.Once + file_connector_v1_connector_proto_rawDescData []byte +) + +func file_connector_v1_connector_proto_rawDescGZIP() []byte { + file_connector_v1_connector_proto_rawDescOnce.Do(func() { + file_connector_v1_connector_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_connector_v1_connector_proto_rawDesc), len(file_connector_v1_connector_proto_rawDesc))) + }) + return file_connector_v1_connector_proto_rawDescData +} + +var file_connector_v1_connector_proto_enumTypes = make([]protoimpl.EnumInfo, 1) +var file_connector_v1_connector_proto_msgTypes = make([]protoimpl.MessageInfo, 21) +var file_connector_v1_connector_proto_goTypes = []any{ + (Reversibility)(0), // 0: connector.v1.Reversibility + (*ConfigureRequest)(nil), // 1: connector.v1.ConfigureRequest + (*ConfigureResponse)(nil), // 2: connector.v1.ConfigureResponse + (*DescribeRequest)(nil), // 3: connector.v1.DescribeRequest + (*DescribeResponse)(nil), // 4: connector.v1.DescribeResponse + (*EventType)(nil), // 5: connector.v1.EventType + (*ActionType)(nil), // 6: connector.v1.ActionType + (*LookupType)(nil), // 7: connector.v1.LookupType + (*Effect)(nil), // 8: connector.v1.Effect + (*Target)(nil), // 9: connector.v1.Target + (*ParseRequest)(nil), // 10: connector.v1.ParseRequest + (*ParseResponse)(nil), // 11: connector.v1.ParseResponse + (*Event)(nil), // 12: connector.v1.Event + (*ResolveRequest)(nil), // 13: connector.v1.ResolveRequest + (*ResolveResponse)(nil), // 14: connector.v1.ResolveResponse + (*InvokeRequest)(nil), // 15: connector.v1.InvokeRequest + (*InvokeResponse)(nil), // 16: connector.v1.InvokeResponse + (*LookupRequest)(nil), // 17: connector.v1.LookupRequest + (*LookupResponse)(nil), // 18: connector.v1.LookupResponse + nil, // 19: connector.v1.ConfigureRequest.SettingsEntry + nil, // 20: connector.v1.ConfigureRequest.SecretsEntry + nil, // 21: connector.v1.ParseRequest.HeadersEntry + (*timestamppb.Timestamp)(nil), // 22: google.protobuf.Timestamp +} +var file_connector_v1_connector_proto_depIdxs = []int32{ + 19, // 0: connector.v1.ConfigureRequest.settings:type_name -> connector.v1.ConfigureRequest.SettingsEntry + 20, // 1: connector.v1.ConfigureRequest.secrets:type_name -> connector.v1.ConfigureRequest.SecretsEntry + 5, // 2: connector.v1.DescribeResponse.events:type_name -> connector.v1.EventType + 6, // 3: connector.v1.DescribeResponse.actions:type_name -> connector.v1.ActionType + 7, // 4: connector.v1.DescribeResponse.lookups:type_name -> connector.v1.LookupType + 8, // 5: connector.v1.ActionType.effect:type_name -> connector.v1.Effect + 0, // 6: connector.v1.Effect.reversibility:type_name -> connector.v1.Reversibility + 21, // 7: connector.v1.ParseRequest.headers:type_name -> connector.v1.ParseRequest.HeadersEntry + 12, // 8: connector.v1.ParseResponse.events:type_name -> connector.v1.Event + 22, // 9: connector.v1.Event.occurred_at:type_name -> google.protobuf.Timestamp + 9, // 10: connector.v1.ResolveResponse.target:type_name -> connector.v1.Target + 8, // 11: connector.v1.ResolveResponse.effect:type_name -> connector.v1.Effect + 1, // 12: connector.v1.ConnectorService.Configure:input_type -> connector.v1.ConfigureRequest + 3, // 13: connector.v1.ConnectorService.Describe:input_type -> connector.v1.DescribeRequest + 10, // 14: connector.v1.ConnectorService.Parse:input_type -> connector.v1.ParseRequest + 13, // 15: connector.v1.ConnectorService.Resolve:input_type -> connector.v1.ResolveRequest + 15, // 16: connector.v1.ConnectorService.Invoke:input_type -> connector.v1.InvokeRequest + 17, // 17: connector.v1.ConnectorService.Lookup:input_type -> connector.v1.LookupRequest + 2, // 18: connector.v1.ConnectorService.Configure:output_type -> connector.v1.ConfigureResponse + 4, // 19: connector.v1.ConnectorService.Describe:output_type -> connector.v1.DescribeResponse + 11, // 20: connector.v1.ConnectorService.Parse:output_type -> connector.v1.ParseResponse + 14, // 21: connector.v1.ConnectorService.Resolve:output_type -> connector.v1.ResolveResponse + 16, // 22: connector.v1.ConnectorService.Invoke:output_type -> connector.v1.InvokeResponse + 18, // 23: connector.v1.ConnectorService.Lookup:output_type -> connector.v1.LookupResponse + 18, // [18:24] is the sub-list for method output_type + 12, // [12:18] is the sub-list for method input_type + 12, // [12:12] is the sub-list for extension type_name + 12, // [12:12] is the sub-list for extension extendee + 0, // [0:12] is the sub-list for field type_name +} + +func init() { file_connector_v1_connector_proto_init() } +func file_connector_v1_connector_proto_init() { + if File_connector_v1_connector_proto != nil { + return + } + type x struct{} + out := protoimpl.TypeBuilder{ + File: protoimpl.DescBuilder{ + GoPackagePath: reflect.TypeOf(x{}).PkgPath(), + RawDescriptor: unsafe.Slice(unsafe.StringData(file_connector_v1_connector_proto_rawDesc), len(file_connector_v1_connector_proto_rawDesc)), + NumEnums: 1, + NumMessages: 21, + NumExtensions: 0, + NumServices: 1, + }, + GoTypes: file_connector_v1_connector_proto_goTypes, + DependencyIndexes: file_connector_v1_connector_proto_depIdxs, + EnumInfos: file_connector_v1_connector_proto_enumTypes, + MessageInfos: file_connector_v1_connector_proto_msgTypes, + }.Build() + File_connector_v1_connector_proto = out.File + file_connector_v1_connector_proto_goTypes = nil + file_connector_v1_connector_proto_depIdxs = nil +} diff --git a/internal/contracts/connector/v1/connector_grpc.pb.go b/internal/contracts/connector/v1/connector_grpc.pb.go new file mode 100644 index 000000000..dea90db04 --- /dev/null +++ b/internal/contracts/connector/v1/connector_grpc.pb.go @@ -0,0 +1,343 @@ +// Code generated by protoc-gen-go-grpc. DO NOT EDIT. +// versions: +// - protoc-gen-go-grpc v1.6.2 +// - protoc (unknown) +// source: connector/v1/connector.proto + +package connectorv1 + +import ( + context "context" + grpc "google.golang.org/grpc" + codes "google.golang.org/grpc/codes" + status "google.golang.org/grpc/status" +) + +// This is a compile-time assertion to ensure that this generated file +// is compatible with the grpc package it is being compiled against. +// Requires gRPC-Go v1.64.0 or later. +const _ = grpc.SupportPackageIsVersion9 + +const ( + ConnectorService_Configure_FullMethodName = "/connector.v1.ConnectorService/Configure" + ConnectorService_Describe_FullMethodName = "/connector.v1.ConnectorService/Describe" + ConnectorService_Parse_FullMethodName = "/connector.v1.ConnectorService/Parse" + ConnectorService_Resolve_FullMethodName = "/connector.v1.ConnectorService/Resolve" + ConnectorService_Invoke_FullMethodName = "/connector.v1.ConnectorService/Invoke" + ConnectorService_Lookup_FullMethodName = "/connector.v1.ConnectorService/Lookup" +) + +// ConnectorServiceClient is the client API for ConnectorService service. +// +// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// 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. +type ConnectorServiceClient interface { + // Configure hands the connector its operator settings and resolved secrets. + // The host calls it once after launch and again when settings change. + Configure(ctx context.Context, in *ConfigureRequest, opts ...grpc.CallOption) (*ConfigureResponse, error) + // Describe declares the connector's event types, actions and lookups. + Describe(ctx context.Context, in *DescribeRequest, opts ...grpc.CallOption) (*DescribeResponse, error) + // Parse turns a payload the host has already verified into typed events. + Parse(ctx context.Context, in *ParseRequest, opts ...grpc.CallOption) (*ParseResponse, error) + // 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. + Resolve(ctx context.Context, in *ResolveRequest, opts ...grpc.CallOption) (*ResolveResponse, error) + // Invoke runs one judged action. The connector honours the idempotency key + // and returns the digest of what it actually executed. + Invoke(ctx context.Context, in *InvokeRequest, opts ...grpc.CallOption) (*InvokeResponse, error) + // Lookup answers a read-only question. Lookups change nothing and run no + // guards; a lookup that finds nothing says so. + Lookup(ctx context.Context, in *LookupRequest, opts ...grpc.CallOption) (*LookupResponse, error) +} + +type connectorServiceClient struct { + cc grpc.ClientConnInterface +} + +func NewConnectorServiceClient(cc grpc.ClientConnInterface) ConnectorServiceClient { + return &connectorServiceClient{cc} +} + +func (c *connectorServiceClient) Configure(ctx context.Context, in *ConfigureRequest, opts ...grpc.CallOption) (*ConfigureResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(ConfigureResponse) + err := c.cc.Invoke(ctx, ConnectorService_Configure_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + +func (c *connectorServiceClient) Describe(ctx context.Context, in *DescribeRequest, opts ...grpc.CallOption) (*DescribeResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(DescribeResponse) + err := c.cc.Invoke(ctx, ConnectorService_Describe_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + +func (c *connectorServiceClient) Parse(ctx context.Context, in *ParseRequest, opts ...grpc.CallOption) (*ParseResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(ParseResponse) + err := c.cc.Invoke(ctx, ConnectorService_Parse_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + +func (c *connectorServiceClient) Resolve(ctx context.Context, in *ResolveRequest, opts ...grpc.CallOption) (*ResolveResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(ResolveResponse) + err := c.cc.Invoke(ctx, ConnectorService_Resolve_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + +func (c *connectorServiceClient) Invoke(ctx context.Context, in *InvokeRequest, opts ...grpc.CallOption) (*InvokeResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(InvokeResponse) + err := c.cc.Invoke(ctx, ConnectorService_Invoke_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + +func (c *connectorServiceClient) Lookup(ctx context.Context, in *LookupRequest, opts ...grpc.CallOption) (*LookupResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(LookupResponse) + err := c.cc.Invoke(ctx, ConnectorService_Lookup_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + +// ConnectorServiceServer is the server API for ConnectorService service. +// All implementations must embed UnimplementedConnectorServiceServer +// for forward compatibility. +// +// 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. +type ConnectorServiceServer interface { + // Configure hands the connector its operator settings and resolved secrets. + // The host calls it once after launch and again when settings change. + Configure(context.Context, *ConfigureRequest) (*ConfigureResponse, error) + // Describe declares the connector's event types, actions and lookups. + Describe(context.Context, *DescribeRequest) (*DescribeResponse, error) + // Parse turns a payload the host has already verified into typed events. + Parse(context.Context, *ParseRequest) (*ParseResponse, error) + // 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. + Resolve(context.Context, *ResolveRequest) (*ResolveResponse, error) + // Invoke runs one judged action. The connector honours the idempotency key + // and returns the digest of what it actually executed. + Invoke(context.Context, *InvokeRequest) (*InvokeResponse, error) + // Lookup answers a read-only question. Lookups change nothing and run no + // guards; a lookup that finds nothing says so. + Lookup(context.Context, *LookupRequest) (*LookupResponse, error) + mustEmbedUnimplementedConnectorServiceServer() +} + +// UnimplementedConnectorServiceServer must be embedded to have +// forward compatible implementations. +// +// NOTE: this should be embedded by value instead of pointer to avoid a nil +// pointer dereference when methods are called. +type UnimplementedConnectorServiceServer struct{} + +func (UnimplementedConnectorServiceServer) Configure(context.Context, *ConfigureRequest) (*ConfigureResponse, error) { + return nil, status.Error(codes.Unimplemented, "method Configure not implemented") +} +func (UnimplementedConnectorServiceServer) Describe(context.Context, *DescribeRequest) (*DescribeResponse, error) { + return nil, status.Error(codes.Unimplemented, "method Describe not implemented") +} +func (UnimplementedConnectorServiceServer) Parse(context.Context, *ParseRequest) (*ParseResponse, error) { + return nil, status.Error(codes.Unimplemented, "method Parse not implemented") +} +func (UnimplementedConnectorServiceServer) Resolve(context.Context, *ResolveRequest) (*ResolveResponse, error) { + return nil, status.Error(codes.Unimplemented, "method Resolve not implemented") +} +func (UnimplementedConnectorServiceServer) Invoke(context.Context, *InvokeRequest) (*InvokeResponse, error) { + return nil, status.Error(codes.Unimplemented, "method Invoke not implemented") +} +func (UnimplementedConnectorServiceServer) Lookup(context.Context, *LookupRequest) (*LookupResponse, error) { + return nil, status.Error(codes.Unimplemented, "method Lookup not implemented") +} +func (UnimplementedConnectorServiceServer) mustEmbedUnimplementedConnectorServiceServer() {} +func (UnimplementedConnectorServiceServer) testEmbeddedByValue() {} + +// UnsafeConnectorServiceServer may be embedded to opt out of forward compatibility for this service. +// Use of this interface is not recommended, as added methods to ConnectorServiceServer will +// result in compilation errors. +type UnsafeConnectorServiceServer interface { + mustEmbedUnimplementedConnectorServiceServer() +} + +func RegisterConnectorServiceServer(s grpc.ServiceRegistrar, srv ConnectorServiceServer) { + // If the following call panics, it indicates UnimplementedConnectorServiceServer was + // embedded by pointer and is nil. This will cause panics if an + // unimplemented method is ever invoked, so we test this at initialization + // time to prevent it from happening at runtime later due to I/O. + if t, ok := srv.(interface{ testEmbeddedByValue() }); ok { + t.testEmbeddedByValue() + } + s.RegisterService(&ConnectorService_ServiceDesc, srv) +} + +func _ConnectorService_Configure_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(ConfigureRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(ConnectorServiceServer).Configure(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: ConnectorService_Configure_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(ConnectorServiceServer).Configure(ctx, req.(*ConfigureRequest)) + } + return interceptor(ctx, in, info, handler) +} + +func _ConnectorService_Describe_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(DescribeRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(ConnectorServiceServer).Describe(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: ConnectorService_Describe_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(ConnectorServiceServer).Describe(ctx, req.(*DescribeRequest)) + } + return interceptor(ctx, in, info, handler) +} + +func _ConnectorService_Parse_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(ParseRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(ConnectorServiceServer).Parse(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: ConnectorService_Parse_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(ConnectorServiceServer).Parse(ctx, req.(*ParseRequest)) + } + return interceptor(ctx, in, info, handler) +} + +func _ConnectorService_Resolve_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(ResolveRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(ConnectorServiceServer).Resolve(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: ConnectorService_Resolve_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(ConnectorServiceServer).Resolve(ctx, req.(*ResolveRequest)) + } + return interceptor(ctx, in, info, handler) +} + +func _ConnectorService_Invoke_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(InvokeRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(ConnectorServiceServer).Invoke(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: ConnectorService_Invoke_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(ConnectorServiceServer).Invoke(ctx, req.(*InvokeRequest)) + } + return interceptor(ctx, in, info, handler) +} + +func _ConnectorService_Lookup_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(LookupRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(ConnectorServiceServer).Lookup(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: ConnectorService_Lookup_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(ConnectorServiceServer).Lookup(ctx, req.(*LookupRequest)) + } + return interceptor(ctx, in, info, handler) +} + +// ConnectorService_ServiceDesc is the grpc.ServiceDesc for ConnectorService service. +// It's only intended for direct use with grpc.RegisterService, +// and not to be introspected or modified (even as a copy) +var ConnectorService_ServiceDesc = grpc.ServiceDesc{ + ServiceName: "connector.v1.ConnectorService", + HandlerType: (*ConnectorServiceServer)(nil), + Methods: []grpc.MethodDesc{ + { + MethodName: "Configure", + Handler: _ConnectorService_Configure_Handler, + }, + { + MethodName: "Describe", + Handler: _ConnectorService_Describe_Handler, + }, + { + MethodName: "Parse", + Handler: _ConnectorService_Parse_Handler, + }, + { + MethodName: "Resolve", + Handler: _ConnectorService_Resolve_Handler, + }, + { + MethodName: "Invoke", + Handler: _ConnectorService_Invoke_Handler, + }, + { + MethodName: "Lookup", + Handler: _ConnectorService_Lookup_Handler, + }, + }, + Streams: []grpc.StreamDesc{}, + Metadata: "connector/v1/connector.proto", +} diff --git a/modules/connectors/connector.go b/modules/connectors/connector.go new file mode 100644 index 000000000..d099c81dc --- /dev/null +++ b/modules/connectors/connector.go @@ -0,0 +1,296 @@ +package connectors + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "time" + + "github.com/google/jsonschema-go/jsonschema" + + pb "github.com/samcharles93/archie-core/internal/contracts/connector/v1" +) + +var ( + // ErrDigestMismatch means the connector ran something other than the + // judged action. It is a finding and tightens the action class. + ErrDigestMismatch = errors.New("connector executed a different action than the one judged") + // ErrOutcomeUnknown means the connector can't confirm what its effect did. + ErrOutcomeUnknown = errors.New("connector can't confirm the outcome") + // ErrNotIdempotent refuses an action with external effects from a + // connector that doesn't honour idempotency keys. + ErrNotIdempotent = errors.New("action has external effects but the connector doesn't declare idempotency") + // ErrUnknownName names an action, lookup or event type the connector + // never declared. + ErrUnknownName = errors.New("not declared by the connector") +) + +// Reversibility says whether and how an action can be undone. +type Reversibility int + +// Reversibility values, in the order of decreasing autonomy they allow. +const ( + ReversibilityUnspecified Reversibility = iota + UndoneAutomatically + Recoverable + Irreversible +) + +// Effect describes what one action does. +type Effect struct { + ReadOnly bool + Reversibility Reversibility + Summary string +} + +// Target is what an action acts on. Connector, action, kind and environment +// together are the action class. +type Target struct { + Kind string + ID string + Environment string + Disposable bool +} + +// Resolution is an action's target and the effect it would have there. +type Resolution struct { + Target Target + Effect Effect +} + +// Event is one typed event a connector parsed from a verified payload. +type Event struct { + Type string + SourceEventID string + Fields json.RawMessage + LinkKey string + OccurredAt time.Time +} + +// Invocation is one judged action to run. +type Invocation struct { + Action string + Input json.RawMessage + IdempotencyKey string +} + +type action struct { + effect Effect + idempotent bool + input *jsonschema.Resolved +} + +// Connector is a running connector and what it declared. +type Connector struct { + name string + client pb.ConnectorServiceClient + events map[string]*jsonschema.Resolved + actions map[string]action + lookups map[string]*jsonschema.Resolved +} + +// open configures a connector and reads its declaration. +func open(ctx context.Context, name string, client pb.ConnectorServiceClient, settings, secrets map[string]string) (*Connector, error) { + if _, err := client.Configure(ctx, &pb.ConfigureRequest{Settings: settings, Secrets: secrets}); err != nil { + return nil, fmt.Errorf("connector %q: configure: %w", name, err) + } + desc, err := client.Describe(ctx, &pb.DescribeRequest{}) + if err != nil { + return nil, fmt.Errorf("connector %q: describe: %w", name, err) + } + if desc.GetContract() != contractVersion { + return nil, fmt.Errorf("connector %q speaks contract %q, the host speaks %q", name, desc.GetContract(), contractVersion) + } + c := &Connector{ + name: name, client: client, + events: map[string]*jsonschema.Resolved{}, + actions: map[string]action{}, + lookups: map[string]*jsonschema.Resolved{}, + } + return c, c.load(desc) +} + +func (c *Connector) load(desc *pb.DescribeResponse) error { + for _, e := range desc.GetEvents() { + s, err := compile(e.GetSchema()) + if err != nil { + return fmt.Errorf("connector %q: event %q: %w", c.name, e.GetName(), err) + } + c.events[e.GetName()] = s + } + for _, a := range desc.GetActions() { + s, err := compile(a.GetInputSchema()) + if err != nil { + return fmt.Errorf("connector %q: action %q: %w", c.name, a.GetName(), err) + } + c.actions[a.GetName()] = action{effect: effectFrom(a.GetEffect()), idempotent: a.GetIdempotent(), input: s} + } + for _, l := range desc.GetLookups() { + s, err := compile(l.GetInputSchema()) + if err != nil { + return fmt.Errorf("connector %q: lookup %q: %w", c.name, l.GetName(), err) + } + c.lookups[l.GetName()] = s + } + return nil +} + +// Name is the connector's accepted name. +func (c *Connector) Name() string { return c.name } + +// Parse turns a payload the caller has already verified into typed events, +// each checked against its declared schema. +func (c *Connector) Parse(ctx context.Context, body []byte, headers map[string]string) ([]Event, error) { + resp, err := c.client.Parse(ctx, &pb.ParseRequest{Body: body, Headers: headers}) + if err != nil { + return nil, fmt.Errorf("connector %q: parse: %w", c.name, err) + } + events := make([]Event, 0, len(resp.GetEvents())) + for _, e := range resp.GetEvents() { + schema, ok := c.events[e.GetType()] + if !ok { + return nil, fmt.Errorf("connector %q: event type %q: %w", c.name, e.GetType(), ErrUnknownName) + } + if err := validate(schema, e.GetFields()); err != nil { + return nil, fmt.Errorf("connector %q: event %q: %w", c.name, e.GetType(), err) + } + events = append(events, Event{ + Type: e.GetType(), SourceEventID: e.GetSourceEventId(), Fields: e.GetFields(), + LinkKey: e.GetLinkKey(), OccurredAt: e.GetOccurredAt().AsTime(), + }) + } + return events, nil +} + +// Resolve returns the target and effect of one concrete action. +func (c *Connector) Resolve(ctx context.Context, name string, input json.RawMessage) (Resolution, error) { + if _, err := c.action(name, input); err != nil { + return Resolution{}, err + } + resp, err := c.client.Resolve(ctx, &pb.ResolveRequest{Action: name, Input: input}) + if err != nil { + return Resolution{}, fmt.Errorf("connector %q: resolve %q: %w", c.name, name, err) + } + t := resp.GetTarget() + return Resolution{ + Target: Target{Kind: t.GetKind(), ID: t.GetId(), Environment: t.GetEnvironment(), Disposable: t.GetDisposable()}, + Effect: effectFrom(resp.GetEffect()), + }, nil +} + +// Invoke runs one judged action and decodes its output into T. The connector +// must report the digest of what it ran; a different digest is refused. +func (c *Connector) Invoke[T any](ctx context.Context, inv Invocation) (T, error) { + var zero T + a, err := c.action(inv.Action, inv.Input) + if err != nil { + return zero, err + } + if !a.effect.ReadOnly && !a.idempotent { + return zero, fmt.Errorf("connector %q: action %q: %w", c.name, inv.Action, ErrNotIdempotent) + } + digest := Digest(inv.Action, inv.Input) + resp, err := c.client.Invoke(ctx, &pb.InvokeRequest{ + Action: inv.Action, Input: inv.Input, IdempotencyKey: inv.IdempotencyKey, Digest: digest, + }) + if err != nil { + return zero, fmt.Errorf("connector %q: invoke %q: %w", c.name, inv.Action, err) + } + if resp.GetExecutedDigest() != digest { + return zero, fmt.Errorf("connector %q: action %q: %w", c.name, inv.Action, ErrDigestMismatch) + } + if resp.GetOutcomeUnknown() { + return zero, fmt.Errorf("connector %q: action %q: %w", c.name, inv.Action, ErrOutcomeUnknown) + } + return decode[T](resp.GetOutput()) +} + +// Lookup answers a read-only question and decodes the answer into T. found is +// false when the connector found nothing, which callers report as a finding. +func (c *Connector) Lookup[T any](ctx context.Context, name string, input json.RawMessage) (T, bool, error) { + var zero T + schema, ok := c.lookups[name] + if !ok { + return zero, false, fmt.Errorf("connector %q: lookup %q: %w", c.name, name, ErrUnknownName) + } + if err := validate(schema, input); err != nil { + return zero, false, fmt.Errorf("connector %q: lookup %q: %w", c.name, name, err) + } + resp, err := c.client.Lookup(ctx, &pb.LookupRequest{Lookup: name, Input: input}) + if err != nil { + return zero, false, fmt.Errorf("connector %q: lookup %q: %w", c.name, name, err) + } + if !resp.GetFound() { + return zero, false, nil + } + out, err := decode[T](resp.GetOutput()) + return out, err == nil, err +} + +func (c *Connector) action(name string, input json.RawMessage) (action, error) { + a, ok := c.actions[name] + if !ok { + return action{}, fmt.Errorf("connector %q: action %q: %w", c.name, name, ErrUnknownName) + } + if err := validate(a.input, input); err != nil { + return action{}, fmt.Errorf("connector %q: action %q: %w", c.name, name, err) + } + return a, nil +} + +// Digest identifies one concrete action: its name and its exact input. The +// connector SDK computes the same digest over what it ran. +func Digest(action string, input json.RawMessage) string { + h := sha256.New() + h.Write([]byte(action)) + h.Write([]byte{0}) + h.Write(input) + return hex.EncodeToString(h.Sum(nil)) +} + +func effectFrom(e *pb.Effect) Effect { + return Effect{ReadOnly: e.GetReadOnly(), Reversibility: Reversibility(e.GetReversibility()), Summary: e.GetSummary()} +} + +func compile(raw []byte) (*jsonschema.Resolved, error) { + if len(raw) == 0 { + raw = []byte(`{}`) + } + var s jsonschema.Schema + if err := json.Unmarshal(raw, &s); err != nil { + return nil, fmt.Errorf("schema: %w", err) + } + resolved, err := s.Resolve(nil) + if err != nil { + return nil, fmt.Errorf("schema: %w", err) + } + return resolved, nil +} + +func validate(schema *jsonschema.Resolved, raw json.RawMessage) error { + if len(raw) == 0 { + raw = json.RawMessage(`{}`) + } + var instance any + if err := json.Unmarshal(raw, &instance); err != nil { + return fmt.Errorf("payload is not JSON: %w", err) + } + if err := schema.Validate(instance); err != nil { + return fmt.Errorf("payload doesn't match its schema: %w", err) + } + return nil +} + +func decode[T any](raw []byte) (T, error) { + var out T + if len(raw) == 0 { + return out, nil + } + if err := json.Unmarshal(raw, &out); err != nil { + return out, fmt.Errorf("decode connector output: %w", err) + } + return out, nil +} diff --git a/modules/connectors/connector_test.go b/modules/connectors/connector_test.go new file mode 100644 index 000000000..a05f042b9 --- /dev/null +++ b/modules/connectors/connector_test.go @@ -0,0 +1,96 @@ +package connectors + +import ( + "context" + "encoding/json" + "errors" + "testing" + + "google.golang.org/grpc" + + pb "github.com/samcharles93/archie-core/internal/contracts/connector/v1" +) + +// fakeClient is a connector that declares one action and answers Invoke as +// told, so the host's checks can be driven directly. +type fakeClient struct { + pb.ConnectorServiceClient + readOnly bool + idempotent bool + // executed overrides the digest the connector reports; empty echoes the + // host's digest. + executed string + unknown bool + invoked int +} + +func (f *fakeClient) Configure(context.Context, *pb.ConfigureRequest, ...grpc.CallOption) (*pb.ConfigureResponse, error) { + return &pb.ConfigureResponse{}, nil +} + +func (f *fakeClient) Describe(context.Context, *pb.DescribeRequest, ...grpc.CallOption) (*pb.DescribeResponse, error) { + return &pb.DescribeResponse{Contract: contractVersion, Actions: []*pb.ActionType{{ + Name: "delete", + InputSchema: []byte(`{"type":"object","required":["path"],"properties":{"path":{"type":"string"}}}`), + Effect: &pb.Effect{ReadOnly: f.readOnly, Reversibility: pb.Reversibility_REVERSIBILITY_RECOVERABLE}, + Idempotent: f.idempotent, + }}}, nil +} + +func (f *fakeClient) Invoke(_ context.Context, req *pb.InvokeRequest, _ ...grpc.CallOption) (*pb.InvokeResponse, error) { + f.invoked++ + executed := req.GetDigest() + if f.executed != "" { + executed = f.executed + } + return &pb.InvokeResponse{Output: []byte(`{"deleted":3}`), ExecutedDigest: executed, OutcomeUnknown: f.unknown}, nil +} + +// TestInvokeRunsOnlyTheJudgedAction guards R18 and 2.5's checks at the +// connector boundary: input that breaks the declared schema never reaches the +// connector, an action with external effects is refused unless the connector +// honours idempotency keys, a connector that ran something other than the +// judged action is caught by its digest, and an unconfirmed outcome is +// reported as unknown rather than success. +func TestInvokeRunsOnlyTheJudgedAction(t *testing.T) { + good := json.RawMessage(`{"path":"/tmp/runner"}`) + tests := []struct { + name string + client *fakeClient + input json.RawMessage + wantErr error + wantAnyErr bool + wantInvoked int + }{ + {name: "matching digest returns the output", client: &fakeClient{idempotent: true}, input: good, wantInvoked: 1}, + {name: "a different executed digest is refused", client: &fakeClient{idempotent: true, executed: "other"}, input: good, wantErr: ErrDigestMismatch, wantInvoked: 1}, + {name: "external effects without idempotency are refused before running", client: &fakeClient{}, input: good, wantErr: ErrNotIdempotent}, + {name: "read-only actions need no idempotency", client: &fakeClient{readOnly: true}, input: good, wantInvoked: 1}, + {name: "an unconfirmed outcome is unknown", client: &fakeClient{idempotent: true, unknown: true}, input: good, wantErr: ErrOutcomeUnknown, wantInvoked: 1}, + {name: "input breaking the schema never reaches the connector", client: &fakeClient{idempotent: true}, input: json.RawMessage(`{"path":7}`), wantAnyErr: true, wantInvoked: 0}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + c, err := open(t.Context(), "fake", tt.client, nil, nil) + if err != nil { + t.Fatalf("open: %v", err) + } + out, err := c.Invoke[map[string]int](t.Context(), Invocation{Action: "delete", Input: tt.input, IdempotencyKey: "run:1"}) + wantOK := tt.wantErr == nil && !tt.wantAnyErr + switch { + case wantOK && err != nil: + t.Fatalf("Invoke: %v", err) + case !wantOK && err == nil: + t.Fatal("Invoke succeeded, want an error") + case tt.wantErr != nil && !errors.Is(err, tt.wantErr): + t.Fatalf("Invoke error = %v, want %v", err, tt.wantErr) + } + if wantOK && out["deleted"] != 3 { + t.Fatalf("output = %v, want deleted:3", out) + } + if tt.client.invoked != tt.wantInvoked { + t.Fatalf("connector invoked %d times, want %d", tt.client.invoked, tt.wantInvoked) + } + }) + } +} diff --git a/modules/connectors/connectors.go b/modules/connectors/connectors.go new file mode 100644 index 000000000..d9e5ae7a5 --- /dev/null +++ b/modules/connectors/connectors.go @@ -0,0 +1,93 @@ +// Package connectors hosts connector extensions: one confined subprocess per +// accepted connector, speaking the connector contract (proto/connector/v1). +// Other modules reach a connector only through the Connector this package +// returns, which validates every payload against the connector's declared +// schemas and checks that only the judged action runs. +package connectors + +import ( + "context" + "fmt" + "log/slog" + + goplugin "github.com/hashicorp/go-plugin" + "google.golang.org/grpc" + + pb "github.com/samcharles93/archie-core/internal/contracts/connector/v1" + "github.com/samcharles93/archie-core/modules/connectors/internal/host" +) + +// surface names the connector contract in the plugin handshake. +const surface = "connector" + +// contractVersion is the connector contract this host speaks. +const contractVersion = "v1" + +// Spec is one accepted connector to run. +type Spec struct { + Name string + // Path is the connector binary; SHA256 is the digest it must match. + Path string + SHA256 string + // Env names host environment variables the connector may see. + Env []string + // Egress is the accepted host list. A connector that touches targets + // declares it, and runs confined to those hosts. + Egress []string + Settings map[string]string + Secrets map[string]string +} + +// Host owns the running connectors. +type Host struct { + procs *host.Host +} + +// NewHost returns a host that logs plugin lifecycle to log. +func NewHost(log *slog.Logger) *Host { + return &Host{procs: host.NewHost(log)} +} + +// Start launches spec, configures it and reads its declaration. A connector +// already running under the same name is replaced. +func (h *Host) Start(ctx context.Context, spec Spec) (*Connector, error) { + raw, err := h.procs.Start(ctx, host.Spec{ + Name: spec.Name, Path: spec.Path, SHA256: spec.SHA256, Env: spec.Env, Egress: spec.Egress, + }, surface, &plugin{}) + if err != nil { + return nil, err + } + client, ok := raw.(pb.ConnectorServiceClient) + if !ok { + h.procs.Stop(spec.Name) + return nil, fmt.Errorf("connector %q: plugin is not a connector", spec.Name) + } + c, err := open(ctx, spec.Name, client, spec.Settings, spec.Secrets) + if err != nil { + h.procs.Stop(spec.Name) + return nil, err + } + return c, nil +} + +// Stop ends the named connector. +func (h *Host) Stop(name string) { h.procs.Stop(name) } + +// Alive reports whether the named connector's process is running. +func (h *Host) Alive(name string) bool { return h.procs.Alive(name) } + +// Close stops every connector. +func (h *Host) Close() { h.procs.Close() } + +// plugin is the host side of the go-plugin handshake for the contract. +type plugin struct { + goplugin.NetRPCUnsupportedPlugin +} + +func (*plugin) GRPCServer(*goplugin.GRPCBroker, *grpc.Server) error { + return fmt.Errorf("connectors are served by extensions, not by the host") +} + +func (*plugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, conn *grpc.ClientConn) (any, error) { + return pb.NewConnectorServiceClient(conn), nil +} diff --git a/modules/connectors/internal/egress/policy.go b/modules/connectors/internal/egress/policy.go new file mode 100644 index 000000000..1f66abb50 --- /dev/null +++ b/modules/connectors/internal/egress/policy.go @@ -0,0 +1,88 @@ +package egress + +import ( + "net" + "strconv" + "strings" +) + +// pattern is one allow-list entry: an exact host, a host on one port, +// a single-label wildcard, or everything. +type pattern struct { + everything bool + suffix string // ".example.com" for "*.example.com" + host string + port int // 0 means any port +} + +// rules is a compiled allow list. An empty one allows nothing. +type rules struct { + allow []pattern +} + +func compilePatterns(entries []string) []pattern { + out := make([]pattern, 0, len(entries)) + for _, e := range entries { + out = append(out, compilePattern(e)) + } + return out +} + +func compilePattern(entry string) pattern { + entry = strings.TrimSpace(entry) + if entry == "*" || entry == "**" { + return pattern{everything: true} + } + var p pattern + if h, portText, err := net.SplitHostPort(entry); err == nil { + if port, err := strconv.Atoi(portText); err == nil { + entry, p.port = h, port + } + } + entry = normalizeHost(entry) + if rest, ok := strings.CutPrefix(entry, "*."); ok { + p.suffix = "." + rest + return p + } + p.host = entry + return p +} + +func normalizeHost(host string) string { + return strings.TrimSuffix(strings.ToLower(host), ".") +} + +func (p pattern) matches(host string, port int) bool { + if p.everything { + return true + } + if p.port != 0 && p.port != port { + return false + } + if p.suffix != "" { + label, ok := strings.CutSuffix(host, p.suffix) + return ok && label != "" && !strings.Contains(label, ".") && net.ParseIP(host) == nil + } + return host == p.host +} + +func (r rules) allows(host string, port int) bool { + host = normalizeHost(host) + for _, p := range r.allow { + if p.matches(host, port) { + return true + } + } + return false +} + +// namesHost reports whether an allow entry names host exactly, as a DNS name +// and not through a wildcard. +func (r rules) namesHost(host string) bool { + for _, p := range r.allow { + if !p.everything && p.suffix == "" && p.host == host { + return true + } + } + return false +} diff --git a/modules/connectors/internal/egress/tunnel.go b/modules/connectors/internal/egress/tunnel.go new file mode 100644 index 000000000..4ca7d4b37 --- /dev/null +++ b/modules/connectors/internal/egress/tunnel.go @@ -0,0 +1,148 @@ +// Package egress is the allow-list tunnel an extension's confined network +// namespace reaches its accepted hosts through. +package egress + +import ( + "context" + "fmt" + "io" + "net" + "net/http" + "net/http/httputil" + "strconv" + "sync" +) + +// Tunnel is an allow-list forward proxy that never terminates TLS: CONNECT is +// spliced byte for byte to an admitted host, and absolute-form http requests +// are forwarded. Extensions get it rather than Proxy because they carry their +// own credentials and never trust the daemon CA. +type Tunnel struct { + rules rules + dial func(ctx context.Context, network, addr string) (net.Conn, error) +} + +// NewTunnel admits the hosts allow names, in network-policy@1 form. A host +// named exactly may resolve to a private address, since the operator named +// it (a LAN forge); a wildcard match may not. Loopback is refused whatever +// is named: it would reach archie's own services. +func NewTunnel(allow []string) *Tunnel { + t := &Tunnel{rules: rules{allow: compilePatterns(allow)}} + t.dial = t.dialGuarded + return t +} + +func (t *Tunnel) ServeHTTP(w http.ResponseWriter, r *http.Request) { + defaultPort, hostport := 443, r.Host + if r.Method != http.MethodConnect { + if !r.URL.IsAbs() || r.URL.Scheme != "http" { + http.Error(w, "only CONNECT and absolute-form http requests are proxied", http.StatusBadRequest) + return + } + defaultPort, hostport = 80, r.URL.Host + } + host, port, err := splitTarget(hostport, defaultPort) + if err != nil { + http.Error(w, err.Error(), http.StatusBadRequest) + return + } + target := net.JoinHostPort(host, strconv.Itoa(port)) + if !t.rules.allows(host, port) { + deny(w, r, "egress to "+target+" is not allowed") + return + } + if r.Method == http.MethodConnect { + t.splice(w, r, target) + return + } + rp := &httputil.ReverseProxy{ + Transport: &http.Transport{DialContext: t.dial}, + FlushInterval: -1, + Rewrite: func(pr *httputil.ProxyRequest) { + pr.Out.URL.Host = target + pr.Out.Header.Del("Proxy-Connection") + }, + ErrorHandler: func(w http.ResponseWriter, _ *http.Request, err error) { + http.Error(w, "upstream "+target+": "+err.Error(), http.StatusBadGateway) + }, + } + rp.ServeHTTP(w, r) +} + +func (t *Tunnel) splice(w http.ResponseWriter, r *http.Request, target string) { + upstream, err := t.dial(r.Context(), "tcp", target) + if err != nil { + http.Error(w, "upstream "+target+": "+err.Error(), http.StatusBadGateway) + return + } + hijacker, ok := w.(http.Hijacker) + if !ok { + _ = upstream.Close() + http.Error(w, "connection cannot be tunnelled", http.StatusInternalServerError) + return + } + client, buffered, err := hijacker.Hijack() + if err != nil { + _ = upstream.Close() + return + } + defer func() { _ = client.Close(); _ = upstream.Close() }() + if _, err := client.Write([]byte("HTTP/1.1 200 Connection Established\r\n\r\n")); err != nil { + return + } + var wg sync.WaitGroup + wg.Go(func() { + _, _ = io.Copy(upstream, buffered) + closeWrite(upstream) + }) + _, _ = io.Copy(client, upstream) + closeWrite(client) + wg.Wait() +} + +// deny refuses a request. Go's client discards the body of a refused CONNECT +// and reports only the reason phrase, so for CONNECT the message is written +// as the reason phrase; otherwise a denial reads as a bare "Forbidden". +func deny(w http.ResponseWriter, r *http.Request, msg string) { + hijacker, ok := w.(http.Hijacker) + if r.Method != http.MethodConnect || !ok { + http.Error(w, msg, http.StatusForbidden) + return + } + conn, _, err := hijacker.Hijack() + if err != nil { + return + } + defer func() { _ = conn.Close() }() + _, _ = fmt.Fprintf(conn, "HTTP/1.1 403 %s\r\nContent-Length: 0\r\nConnection: close\r\n\r\n", msg) +} + +func closeWrite(c net.Conn) { + if cw, ok := c.(interface{ CloseWrite() error }); ok { + _ = cw.CloseWrite() + return + } + _ = c.Close() +} + +// dialGuarded applies the Proxy's upstream guard, counting a host the allow +// list names exactly as naming every address it resolves to. +func (t *Tunnel) dialGuarded(ctx context.Context, network, addr string) (net.Conn, error) { + host, port, err := net.SplitHostPort(addr) + if err != nil { + return nil, err + } + named := t.rules.namesHost(normalizeHost(host)) + addrs, err := net.DefaultResolver.LookupIPAddr(ctx, host) + if err != nil { + return nil, err + } + guardErr := fmt.Errorf("%s resolved to no address", host) + for _, a := range addrs { + if guardErr = guardUpstream(a.IP, named); guardErr != nil { + continue + } + return (&net.Dialer{Timeout: handshakeTimeout}).DialContext(ctx, network, net.JoinHostPort(a.IP.String(), port)) + } + return nil, guardErr +} diff --git a/modules/connectors/internal/egress/upstream.go b/modules/connectors/internal/egress/upstream.go new file mode 100644 index 000000000..8bf5100e1 --- /dev/null +++ b/modules/connectors/internal/egress/upstream.go @@ -0,0 +1,54 @@ +package egress + +import ( + "fmt" + "net" + "strconv" + "strings" + "time" +) + +const handshakeTimeout = 10 * time.Second + +// cgnat is shared address space (RFC 6598), which overlay networks use for +// their addresses; it is internal like the private ranges. +var cgnat = &net.IPNet{IP: net.IPv4(100, 64, 0, 0), Mask: net.CIDRMask(10, 32)} + +// guardUpstream refuses loopback and unspecified addresses always, and +// private, link-local, shared and multicast addresses unless the policy +// named that IP or the host it came from. +func guardUpstream(ip net.IP, trusted bool) error { + if ip.IsLoopback() || ip.IsUnspecified() { + return fmt.Errorf("upstream address %s is the host itself", ip) + } + internal := ip.IsPrivate() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() || + ip.IsInterfaceLocalMulticast() || ip.IsMulticast() || cgnat.Contains(ip) + if internal && !trusted { + return fmt.Errorf("upstream address %s is internal and not named by the network policy", ip) + } + return nil +} + +func splitTarget(hostport string, defaultPort int) (string, int, error) { + if !hasPort(hostport) { + return normalizeHost(strings.Trim(hostport, "[]")), defaultPort, nil + } + host, portText, err := net.SplitHostPort(hostport) + if err != nil { + return "", 0, err + } + port, err := strconv.Atoi(portText) + if err != nil || port <= 0 || port > 65535 { + return "", 0, fmt.Errorf("invalid port in %q", hostport) + } + return normalizeHost(host), port, nil +} + +// hasPort reports whether hostport ends in a port: a bracketed IPv6 literal +// followed by one, or a host with exactly one colon. +func hasPort(hostport string) bool { + if strings.HasPrefix(hostport, "[") { + return strings.Contains(hostport, "]:") + } + return strings.Count(hostport, ":") == 1 +} diff --git a/modules/connectors/internal/host/confine_linux.go b/modules/connectors/internal/host/confine_linux.go new file mode 100644 index 000000000..ec0bb5696 --- /dev/null +++ b/modules/connectors/internal/host/confine_linux.go @@ -0,0 +1,168 @@ +package host + +import ( + "context" + "errors" + "fmt" + "io" + "net" + "os" + "os/exec" + "os/signal" + "runtime" + "syscall" + + "golang.org/x/sys/unix" +) + +// launcherArg makes any binary importing this package the confined +// launcher: the extension's parent inside its network namespace. +const launcherArg = "__extension-egress" + +// proxyAddr is where the launcher serves the extension's only way out. +const proxyAddr = "127.0.0.1:3128" + +func init() { + if len(os.Args) > 2 && os.Args[1] == launcherArg { + os.Exit(launch(os.Args[2])) + } +} + +// confinedCommand re-execs this binary as the launcher in a fresh user and +// network namespace. The namespace holds only loopback, so the extension +// cannot reach anything except through the launcher's relay to socket. Where +// the kernel refuses the namespaces, the start fails: there is no unconfined +// fallback. +func confinedCommand(ctx context.Context, binary *os.File, socket string) (*exec.Cmd, error) { + self, err := os.Executable() + if err != nil { + return nil, err + } + uid, gid := os.Getuid(), os.Getgid() + cmd := exec.CommandContext(ctx, self, launcherArg, socket) + cmd.ExtraFiles = []*os.File{binary} + cmd.SysProcAttr = &syscall.SysProcAttr{ + Cloneflags: syscall.CLONE_NEWUSER | syscall.CLONE_NEWNET, + UidMappings: []syscall.SysProcIDMap{{ContainerID: uid, HostID: uid, Size: 1}}, + GidMappings: []syscall.SysProcIDMap{{ContainerID: gid, HostID: gid, Size: 1}}, + // Only the launcher holds this, to bring loopback up; it clears it + // before the extension starts. + AmbientCaps: []uintptr{unix.CAP_NET_ADMIN}, + Pdeathsig: syscall.SIGKILL, + } + return cmd, nil +} + +// openCommand runs the verified binary by its open descriptor with the host's +// network, for a package that declares no egress hosts. +func openCommand(ctx context.Context, binary *os.File) *exec.Cmd { + path := fmt.Sprintf("/proc/%d/fd/%d", os.Getpid(), binary.Fd()) + cmd := exec.CommandContext(ctx, path) // the host-verified binary, by descriptor + cmd.SysProcAttr = &syscall.SysProcAttr{Pdeathsig: syscall.SIGKILL} + return cmd +} + +// launch runs inside the namespace: loopback up, relay listening, then the +// extension from descriptor 3 with every capability gone. +func launch(socket string) int { + ctx := context.Background() + if err := loopbackUp(); err != nil { + fmt.Fprintln(os.Stderr, "extension egress: loopback:", err) + return 1 + } + ln, err := (&net.ListenConfig{}).Listen(ctx, "tcp", proxyAddr) + if err != nil { + fmt.Fprintln(os.Stderr, "extension egress: relay:", err) + return 1 + } + go relay(ctx, ln, socket) + if err := unix.Prctl(unix.PR_CAP_AMBIENT, unix.PR_CAP_AMBIENT_CLEAR_ALL, 0, 0, 0); err != nil { + fmt.Fprintln(os.Stderr, "extension egress: drop capabilities:", err) + return 1 + } + if err := unix.Prctl(unix.PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0); err != nil { + fmt.Fprintln(os.Stderr, "extension egress: no_new_privs:", err) + return 1 + } + syscall.CloseOnExec(3) + return runExtension(ctx, fmt.Sprintf("/proc/%d/fd/3", os.Getpid())) +} + +// runExtension starts the extension as the launcher's child and mirrors its +// exit. Pdeathsig ties the child to this thread, so killing the launcher +// kills the extension. +func runExtension(ctx context.Context, path string) int { + runtime.LockOSThread() + proxy := "http://" + proxyAddr + cmd := exec.CommandContext(ctx, path) // the host-verified binary, by descriptor + cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr + cmd.Env = append(os.Environ(), + "HTTP_PROXY="+proxy, "HTTPS_PROXY="+proxy, "ALL_PROXY="+proxy, + "http_proxy="+proxy, "https_proxy="+proxy, "all_proxy="+proxy, "NO_PROXY=", "no_proxy=") + cmd.SysProcAttr = &syscall.SysProcAttr{Pdeathsig: syscall.SIGKILL} + if err := cmd.Start(); err != nil { + fmt.Fprintln(os.Stderr, "extension egress: start:", err) + return 1 + } + signals := make(chan os.Signal, 1) + signal.Notify(signals, syscall.SIGINT, syscall.SIGTERM) + go func() { + for s := range signals { + _ = cmd.Process.Signal(s) + } + }() + err := cmd.Wait() + if exit, ok := errors.AsType[*exec.ExitError](err); ok { + return exit.ExitCode() + } + if err != nil { + return 1 + } + return 0 +} + +func loopbackUp() error { + fd, err := unix.Socket(unix.AF_INET, unix.SOCK_DGRAM|unix.SOCK_CLOEXEC, 0) + if err != nil { + return err + } + defer func() { _ = unix.Close(fd) }() + ifr, err := unix.NewIfreq("lo") + if err != nil { + return err + } + if err := unix.IoctlIfreq(fd, unix.SIOCGIFFLAGS, ifr); err != nil { + return err + } + ifr.SetUint16(ifr.Uint16() | unix.IFF_UP) + return unix.IoctlIfreq(fd, unix.SIOCSIFFLAGS, ifr) +} + +// relay carries each proxy connection to the host's gate socket. +func relay(ctx context.Context, ln net.Listener, socket string) { + for { + conn, err := ln.Accept() + if err != nil { + return + } + go func() { + defer func() { _ = conn.Close() }() + upstream, err := (&net.Dialer{}).DialContext(ctx, "unix", socket) + if err != nil { + return + } + defer func() { _ = upstream.Close() }() + go func() { + _, _ = io.Copy(upstream, conn) + closeWrite(upstream) + }() + _, _ = io.Copy(conn, upstream) + }() + } +} + +func closeWrite(c net.Conn) { + if cw, ok := c.(interface{ CloseWrite() error }); ok { + _ = cw.CloseWrite() + } +} diff --git a/modules/connectors/internal/host/confine_other.go b/modules/connectors/internal/host/confine_other.go new file mode 100644 index 000000000..79ee43376 --- /dev/null +++ b/modules/connectors/internal/host/confine_other.go @@ -0,0 +1,20 @@ +//go:build !linux + +package host + +import ( + "context" + "errors" + "os" + "os/exec" +) + +// confinedCommand refuses: extensions run only where their egress can be +// confined to the hosts the operator accepted. +func confinedCommand(context.Context, *os.File, string) (*exec.Cmd, error) { + return nil, errors.New("extensions need Linux network namespaces to confine their egress") +} + +func openCommand(ctx context.Context, binary *os.File) *exec.Cmd { + return exec.CommandContext(ctx, binary.Name()) // the host-verified binary +} diff --git a/modules/connectors/internal/host/gate.go b/modules/connectors/internal/host/gate.go new file mode 100644 index 000000000..07b83f692 --- /dev/null +++ b/modules/connectors/internal/host/gate.go @@ -0,0 +1,48 @@ +package host + +import ( + "context" + "errors" + "fmt" + "net" + "net/http" + "os" + "path/filepath" + "time" + + "github.com/samcharles93/archie-core/modules/connectors/internal/egress" +) + +// gate is the host end of one extension's egress: a Unix socket serving an +// allow-list proxy. A path socket is reachable from the extension's network +// namespace, where nothing else outside it is. +type gate struct { + dir string + socket string + server *http.Server +} + +func openGate(ctx context.Context, allow []string) (*gate, error) { + dir, err := os.MkdirTemp("", "archie-ext-") + if err != nil { + return nil, fmt.Errorf("create egress directory in %s: %w", os.TempDir(), err) + } + g := &gate{dir: dir, socket: filepath.Join(dir, "egress.sock")} + ln, err := (&net.ListenConfig{}).Listen(ctx, "unix", g.socket) + if err != nil { + _ = os.RemoveAll(dir) + return nil, err + } + g.server = &http.Server{Handler: egress.NewTunnel(allow), ReadHeaderTimeout: 30 * time.Second} + go func() { + if err := g.server.Serve(ln); err != nil && !errors.Is(err, http.ErrServerClosed) { + _ = ln.Close() + } + }() + return g, nil +} + +func (g *gate) close() { + _ = g.server.Close() + _ = os.RemoveAll(g.dir) +} diff --git a/modules/connectors/internal/host/hclog.go b/modules/connectors/internal/host/hclog.go new file mode 100644 index 000000000..60e7af473 --- /dev/null +++ b/modules/connectors/internal/host/hclog.go @@ -0,0 +1,119 @@ +package host + +import ( + "context" + "io" + "log" + "log/slog" + "strings" + + "github.com/hashicorp/go-hclog" +) + +// slogger adapts a slog.Logger to the hclog.Logger go-plugin requires, so +// extension lifecycle and plugin output land in the service's own log at its +// configured level. +type slogger struct { + log *slog.Logger + name string + args []any +} + +var _ hclog.Logger = slogger{} + +func newSlogger(log *slog.Logger) hclog.Logger { return slogger{log: log} } + +// levels maps hclog levels to slog; hclog's Trace sits below slog's Debug. +func level(l hclog.Level) slog.Level { + switch l { + case hclog.Trace: + return slog.LevelDebug - 4 + case hclog.Debug: + return slog.LevelDebug + case hclog.Warn: + return slog.LevelWarn + case hclog.Error: + return slog.LevelError + default: + return slog.LevelInfo + } +} + +func (s slogger) Log(l hclog.Level, msg string, args ...any) { + if s.name != "" { + args = append(args, "extension", s.name) + } + s.log.Log(context.Background(), level(l), msg, args...) +} + +func (s slogger) Trace(msg string, args ...any) { s.Log(hclog.Trace, msg, args...) } +func (s slogger) Debug(msg string, args ...any) { s.Log(hclog.Debug, msg, args...) } +func (s slogger) Info(msg string, args ...any) { s.Log(hclog.Info, msg, args...) } +func (s slogger) Warn(msg string, args ...any) { s.Log(hclog.Warn, msg, args...) } +func (s slogger) Error(msg string, args ...any) { s.Log(hclog.Error, msg, args...) } + +func (s slogger) enabled(l hclog.Level) bool { + return s.log.Enabled(context.Background(), level(l)) +} + +func (s slogger) IsTrace() bool { return s.enabled(hclog.Trace) } +func (s slogger) IsDebug() bool { return s.enabled(hclog.Debug) } +func (s slogger) IsInfo() bool { return s.enabled(hclog.Info) } +func (s slogger) IsWarn() bool { return s.enabled(hclog.Warn) } +func (s slogger) IsError() bool { return s.enabled(hclog.Error) } + +func (s slogger) ImpliedArgs() []any { return s.args } + +func (s slogger) With(args ...any) hclog.Logger { + s.log = s.log.With(args...) + s.args = append(append([]any(nil), s.args...), args...) + return s +} + +func (s slogger) Name() string { return s.name } + +func (s slogger) Named(name string) hclog.Logger { + if s.name != "" { + name = s.name + "." + name + } + return s.ResetNamed(name) +} + +func (s slogger) ResetNamed(name string) hclog.Logger { + s.name = name + return s +} + +// SetLevel is a no-op: the service's [log] level decides. +func (slogger) SetLevel(hclog.Level) {} + +func (s slogger) GetLevel() hclog.Level { + for _, l := range []hclog.Level{hclog.Trace, hclog.Debug, hclog.Info, hclog.Warn} { + if s.enabled(l) { + return l + } + } + return hclog.Error +} + +func (s slogger) StandardLogger(opts *hclog.StandardLoggerOptions) *log.Logger { + return log.New(s.StandardWriter(opts), "", 0) +} + +func (s slogger) StandardWriter(opts *hclog.StandardLoggerOptions) io.Writer { + l := hclog.Info + if opts != nil && opts.ForceLevel != hclog.NoLevel { + l = opts.ForceLevel + } + return lineWriter{s: s, level: l} +} + +type lineWriter struct { + s slogger + level hclog.Level +} + +func (w lineWriter) Write(p []byte) (int, error) { + w.s.Log(w.level, strings.TrimRight(string(p), "\n")) + return len(p), nil +} diff --git a/modules/connectors/internal/host/host.go b/modules/connectors/internal/host/host.go new file mode 100644 index 000000000..dba23d347 --- /dev/null +++ b/modules/connectors/internal/host/host.go @@ -0,0 +1,198 @@ +// Package host supervises extension plugins: one go-plugin subprocess per +// enabled extension, each serving a gRPC surface from proto//v1. +package host + +import ( + "bytes" + "context" + "crypto/sha256" + "encoding/hex" + "errors" + "fmt" + "io" + "log/slog" + "os" + "os/exec" + "sync" + + "github.com/hashicorp/go-hclog" + goplugin "github.com/hashicorp/go-plugin" +) + +// Handshake is shared by the host and every extension binary. Bump +// ProtocolVersion on an incompatible change to the handshake itself; each +// surface versions its own proto package. +var Handshake = goplugin.HandshakeConfig{ + ProtocolVersion: 1, + MagicCookieKey: "ARCHIE_EXTENSION", + MagicCookieValue: "archie", +} + +// Spec is one extension to run. +type Spec struct { + Name string + // Path is the extension binary. + Path string + // SHA256 is the hex digest the binary must match before it is launched. + SHA256 string + // Env names the host environment variables the extension may see. PATH and + // HOME are always passed so a plugin can find the CLI it wraps. + Env []string + // Egress is the accepted egress host list. When it names hosts, the + // extension runs in its own network namespace and reaches only these, + // through a proxy; an empty list runs it on the host's network. + Egress []string +} + +// Host owns the running extension processes, keyed by Spec.Name. +type Host struct { + log hclog.Logger + + mu sync.Mutex + procs map[string]*proc +} + +// proc is one running extension and the egress gate it alone can reach. +type proc struct { + client *goplugin.Client + gate *gate +} + +func (p *proc) kill() { + p.client.Kill() + if p.gate != nil { + p.gate.close() + } +} + +// command confines the extension to egress when the package declares hosts. +// A package that declares none opted out of confinement and gets the host's +// network, with no gate. +func command(ctx context.Context, binary *os.File, egress []string) (*exec.Cmd, *gate, error) { + if len(egress) == 0 { + return openCommand(ctx, binary), nil, nil + } + g, err := openGate(ctx, egress) + if err != nil { + return nil, nil, fmt.Errorf("egress: %w", err) + } + cmd, err := confinedCommand(ctx, binary, g.socket) + if err != nil { + g.close() + return nil, nil, err + } + return cmd, g, nil +} + +// NewHost returns a Host that reports plugin lifecycle problems to log. +func NewHost(log *slog.Logger) *Host { + return &Host{log: newSlogger(log), procs: make(map[string]*proc)} +} + +// Start launches spec serving surface and returns the dispensed client. An +// extension already running under the same name is stopped first, so Start is +// also how a changed binary or setting takes effect. +func (h *Host) Start(ctx context.Context, spec Spec, surface string, impl goplugin.Plugin) (any, error) { + sum, err := hex.DecodeString(spec.SHA256) + if err != nil || len(sum) != sha256.Size { + return nil, fmt.Errorf("extension %q: sha256 must be a hex digest", spec.Name) + } + // The verified file is what runs: the confined launcher execs this open + // descriptor, so swapping the path after the check changes nothing. + binary, err := openVerified(spec.Path, sum) + if err != nil { + return nil, fmt.Errorf("extension %q: %w", spec.Name, err) + } + defer func() { _ = binary.Close() }() + cmd, g, err := command(ctx, binary, spec.Egress) + if err != nil { + return nil, fmt.Errorf("extension %q: %w", spec.Name, err) + } + cmd.Env = passEnv(spec.Env) + p := &proc{gate: g, client: goplugin.NewClient(&goplugin.ClientConfig{ + HandshakeConfig: Handshake, + Plugins: goplugin.PluginSet{surface: impl}, + Cmd: cmd, + AllowedProtocols: []goplugin.Protocol{goplugin.ProtocolGRPC}, + SkipHostEnv: true, + AutoMTLS: true, + Logger: h.log.Named(spec.Name), + })} + rpc, err := p.client.Client() + if err != nil { + p.kill() + return nil, fmt.Errorf("extension %q: connect: %w", spec.Name, err) + } + raw, err := rpc.Dispense(surface) + if err != nil { + p.kill() + return nil, fmt.Errorf("extension %q: dispense %s: %w", spec.Name, surface, err) + } + h.mu.Lock() + old := h.procs[spec.Name] + h.procs[spec.Name] = p + h.mu.Unlock() + if old != nil { + old.kill() + } + return raw, nil +} + +// Stop kills the named extension. Stopping one that is not running is not an +// error. +func (h *Host) Stop(name string) { + h.mu.Lock() + p := h.procs[name] + delete(h.procs, name) + h.mu.Unlock() + if p != nil { + p.kill() + } +} + +// Alive reports whether the named extension's process is still running. +func (h *Host) Alive(name string) bool { + h.mu.Lock() + defer h.mu.Unlock() + p := h.procs[name] + return p != nil && !p.client.Exited() +} + +// Close stops every extension. +func (h *Host) Close() { + h.mu.Lock() + procs := h.procs + h.procs = make(map[string]*proc) + h.mu.Unlock() + for _, p := range procs { + p.kill() + } +} + +// openVerified opens the extension binary and checks it against sum. +func openVerified(path string, sum []byte) (*os.File, error) { + f, err := os.Open(path) // the path is the installed package's binary + if err != nil { + return nil, err + } + h := sha256.New() + if _, err := io.Copy(h, f); err != nil { + _ = f.Close() + return nil, err + } + if !bytes.Equal(h.Sum(nil), sum) { + _ = f.Close() + return nil, errors.New("binary does not match its checksum") + } + return f, nil +} + +func passEnv(names []string) []string { + env := make([]string, 0, len(names)+2) + for _, name := range append([]string{"PATH", "HOME"}, names...) { + if value, ok := os.LookupEnv(name); ok { + env = append(env, name+"="+value) + } + } + return env +} diff --git a/proto/connector/v1/connector.proto b/proto/connector/v1/connector.proto new file mode 100644 index 000000000..a17da758f --- /dev/null +++ b/proto/connector/v1/connector.proto @@ -0,0 +1,151 @@ +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 settings = 1; + map 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 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; +}