diff --git a/protobuf/flagd/evaluation/v1/schema.proto b/protobuf/flagd/evaluation/v1/schema.proto new file mode 100644 index 0000000..365b754 --- /dev/null +++ b/protobuf/flagd/evaluation/v1/schema.proto @@ -0,0 +1,193 @@ +/** + * Flag evaluation API + * + * This proto forms the basis of a flag-evaluation API. + * It supports single and bulk evaluation RPCs, and flags of various types, as well as establishing a stream for getting notifications about changes in a flag definition. + * It supports the inclusion of a "context" with each evaluation, which may contain arbitrary attributes relevant to flag evaluation. + */ +syntax = "proto3"; + +package flagd.evaluation.v1; + +import "google/protobuf/struct.proto"; + +option csharp_namespace = "OpenFeature.Flagd.Grpc.Evaluation"; +option go_package = "flagd/evaluation/v1"; +option java_package = "dev.openfeature.flagd.grpc.evaluation"; +option php_namespace = "OpenFeature\\Providers\\Flagd\\Schema\\Grpc\\Evaluation"; +option ruby_package = "OpenFeature::FlagD::Provider::Grpc::Evaluation"; + +// Request body for bulk flag evaluation, used by the ResolveAll rpc. +message ResolveAllRequest { + // Object structure describing the EvaluationContext used in the flag evaluation, see https://openfeature.dev/docs/reference/concepts/evaluation-context + google.protobuf.Struct context = 1; +} + +// Response body for bulk flag evaluation, used by the ResolveAll rpc. +message ResolveAllResponse { + // Object structure describing the evaluated flags for the provided context. + map flags = 1; +} + +// A variant type flag response. +message AnyFlag { + // The reason for the given return value, see https://openfeature.dev/docs/specification/types#resolution-details + string reason = 1; + + // The variant name of the returned flag value. + string variant = 2; + + // The response value of the boolean flag evaluation, will be unset in the case of error. + oneof value { + bool bool_value = 3; + string string_value = 4; + double double_value = 5; + google.protobuf.Struct object_value = 6; + } +} + +// Request body for boolean flag evaluation, used by the ResolveBoolean rpc. +message ResolveBooleanRequest { + // Flag key of the requested flag. + string flag_key = 1; + + // Object structure describing the EvaluationContext used in the flag evaluation, see https://openfeature.dev/docs/reference/concepts/evaluation-context + google.protobuf.Struct context = 2; +} + +// Response body for boolean flag evaluation. used by the ResolveBoolean rpc. +message ResolveBooleanResponse { + // The response value of the boolean flag evaluation, will be unset in the case of error. + bool value = 1; + + // The reason for the given return value, see https://openfeature.dev/docs/specification/types#resolution-details + string reason = 2; + + // The variant name of the returned flag value. + string variant = 3; + + // Metadata for this evaluation + google.protobuf.Struct metadata = 4; +} + +// Request body for string flag evaluation, used by the ResolveString rpc. +message ResolveStringRequest { + // Flag key of the requested flag. + string flag_key = 1; + + // Object structure describing the EvaluationContext used in the flag evaluation, see https://openfeature.dev/docs/reference/concepts/evaluation-context + google.protobuf.Struct context = 2; +} + +// Response body for string flag evaluation. used by the ResolveString rpc. +message ResolveStringResponse { + // The response value of the string flag evaluation, will be unset in the case of error. + string value = 1; + + // The reason for the given return value, see https://openfeature.dev/docs/specification/types#resolution-details + string reason = 2; + + // The variant name of the returned flag value. + string variant = 3; + + // Metadata for this evaluation + google.protobuf.Struct metadata = 4; +} + +// Request body for float flag evaluation, used by the ResolveFloat rpc. +message ResolveFloatRequest { + // Flag key of the requested flag. + string flag_key = 1; + + // Object structure describing the EvaluationContext used in the flag evaluation, see https://openfeature.dev/docs/reference/concepts/evaluation-context + google.protobuf.Struct context = 2; +} + +// Response body for float flag evaluation. used by the ResolveFloat rpc. +message ResolveFloatResponse { + // The response value of the float flag evaluation, will be empty in the case of error. + double value = 1; + + // The reason for the given return value, see https://openfeature.dev/docs/specification/types#resolution-details + string reason = 2; + + // The variant name of the returned flag value. + string variant = 3; + + // Metadata for this evaluation + google.protobuf.Struct metadata = 4; +} + +// Request body for int flag evaluation, used by the ResolveInt rpc. +message ResolveIntRequest { + // Flag key of the requested flag. + string flag_key = 1; + + // Object structure describing the EvaluationContext used in the flag evaluation, see https://openfeature.dev/docs/reference/concepts/evaluation-context + google.protobuf.Struct context = 2; +} + +// Response body for int flag evaluation. used by the ResolveInt rpc. +message ResolveIntResponse { + // The response value of the int flag evaluation, will be unset in the case of error. + int64 value = 1; + + // The reason for the given return value, see https://openfeature.dev/docs/specification/types#resolution-details + string reason = 2; + + // The variant name of the returned flag value. + string variant = 3; + + // Metadata for this evaluation + google.protobuf.Struct metadata = 4; +} + +// Request body for object flag evaluation, used by the ResolveObject rpc. +message ResolveObjectRequest { + // Flag key of the requested flag. + string flag_key = 1; + + // Object structure describing the EvaluationContext used in the flag evaluation, see https://openfeature.dev/docs/reference/concepts/evaluation-context + google.protobuf.Struct context = 2; +} + +// Response body for object flag evaluation. used by the ResolveObject rpc. +message ResolveObjectResponse { + // The response value of the object flag evaluation, will be unset in the case of error. + // + // NOTE: This structure will need to be decoded from google/protobuf/struct.proto before it is returned to the SDK + google.protobuf.Struct value = 1; + + // The reason for the given return value, see https://openfeature.dev/docs/specification/types#resolution-details + string reason = 2; + + // The variant name of the returned flag value. + string variant = 3; + + // Metadata for this evaluation + google.protobuf.Struct metadata = 4; +} + +// Response body for the EventStream stream response +message EventStreamResponse { + // String key indicating the type of event that is being received, for example, provider_ready or configuration_change + string type = 1; + + // Object structure for use when sending relevant metadata to provide context to the event. + // Can be left unset when it is not required. + google.protobuf.Struct data = 2; +} + +// Empty stream request body +message EventStreamRequest {} + +// Service defines the exposed rpcs of flagd +service Service { + rpc ResolveAll(ResolveAllRequest) returns (ResolveAllResponse) {} + rpc ResolveBoolean(ResolveBooleanRequest) returns (ResolveBooleanResponse) {} + rpc ResolveString(ResolveStringRequest) returns (ResolveStringResponse) {} + rpc ResolveFloat(ResolveFloatRequest) returns (ResolveFloatResponse) {} + rpc ResolveInt(ResolveIntRequest) returns (ResolveIntResponse) {} + rpc ResolveObject(ResolveObjectRequest) returns (ResolveObjectResponse) {} + rpc EventStream(EventStreamRequest) returns (stream EventStreamResponse) {} +} diff --git a/protobuf/flagd/sync/v1/schema.proto b/protobuf/flagd/sync/v1/schema.proto new file mode 100644 index 0000000..ba1a961 --- /dev/null +++ b/protobuf/flagd/sync/v1/schema.proto @@ -0,0 +1,93 @@ +/** + * Flag definition sync API + * + * This proto defines a simple API to synchronize a feature flag definition. + * It supports establishing a stream for getting notifications about changes in a flag definition. + */ +syntax = "proto3"; + +package flagd.sync.v1; + +option csharp_namespace = "OpenFeature.Flagd.Grpc.Sync"; +option go_package = "flagd/sync/v1"; +option java_package = "dev.openfeature.flagd.grpc.sync"; +option php_namespace = "OpenFeature\\Providers\\Flagd\\Schema\\Grpc\\Sync"; +option ruby_package = "OpenFeature::FlagD::Provider::Grpc::Sync"; + +// SyncFlagsRequest is the request initiating the sever-streaming rpc. Flagd sends this request, acting as the client +message SyncFlagsRequest { + // Optional: A unique identifier for flagd(grpc client) initiating the request. The server implementations may + // utilize this identifier to uniquely identify, validate(ex:- enforce authentication/authorization) and filter + // flag configurations that it can expose to this request. This field is intended to be optional. However server + // implementations may enforce it. + // ex:- provider_id: flagd-weatherapp-sidecar + string provider_id = 1; + + // Optional: A selector for the flag configuration request. The server implementation may utilize this to select + // flag configurations from a collection, select the source of the flag or combine this to any desired underlying + // filtering mechanism. + // ex:- selector: 'source=database,app=weatherapp' + string selector = 2; +} + +// SyncState conveys the state of the payload. These states are related to flagd isync.go type definitions but +// contains extras to optimize grpc use case. Refer - https://github.com/open-feature/flagd/blob/main/pkg/sync/isync.go +enum SyncState { + // Value is ignored by the listening flagd + SYNC_STATE_UNSPECIFIED = 0; + + // All the flags matching the request. This is the default response and other states can be ignored + // by the implementation. Flagd internally replaces all existing flags for this response state. + SYNC_STATE_ALL = 1; + + // Convey an addition of a flag. Flagd internally handles this by combining new flags with existing ones + SYNC_STATE_ADD = 2; + + // Convey an update of a flag. Flagd internally attempts to update if the updated flag already exist OR if it does not, + // it will get added + SYNC_STATE_UPDATE = 3; + + // Convey a deletion of a flag. Flagd internally removes the flag + SYNC_STATE_DELETE = 4; + + // Optional server ping to check client connectivity. Handling is ignored by flagd and is to merely support live check + SYNC_STATE_PING = 5; +} + +// SyncFlagsResponse is the server response containing feature flag configurations and the state +message SyncFlagsResponse { + // flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/schemas/main/json/flagd-definitions.json + string flag_configuration = 1; + + // State conveying the operation to be performed by flagd. See the descriptions of SyncState for an explanation of + // supported values + SyncState state = 2; +} + +// FetchAllFlagsRequest is the request to fetch all flags. Flagd sends this request as the client in order to resync its internal state +message FetchAllFlagsRequest { + // Optional: A unique identifier for flagd(grpc client) initiating the request. The server implementations may + // utilize this identifier to uniquely identify, validate(ex:- enforce authentication/authorization) and filter + // flag configurations that it can expose to this request. This field is intended to be optional. However server + // implementations may enforce it. + // ex:- provider_id: flagd-weatherapp-sidecar + string provider_id = 1; + + // Optional: A selector for the flag configuration request. The server implementation may utilize this to select + // flag configurations from a collection, select the source of the flag or combine this to any desired underlying + // filtering mechanism. + // ex:- selector: 'source=database,app=weatherapp' + string selector = 2; +} + +// FetchAllFlagsResponse is the server response containing feature flag configurations +message FetchAllFlagsResponse { + // flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/schemas/main/json/flagd-definitions.json + string flag_configuration = 1; +} + +// FlagService implements a server streaming to provide realtime flag configurations +service FlagSyncService { + rpc SyncFlags(SyncFlagsRequest) returns (stream SyncFlagsResponse) {} + rpc FetchAllFlags(FetchAllFlagsRequest) returns (FetchAllFlagsResponse) {} +}