feat: Introduce service definition for GRPC sync contract (#78)

## This PR

Is related to open-feature/ofep#45 &
open-feature/flagd#297

Introduce the service contract of grpc sync. 

Consider checking my personal buf repository -
https://buf.build/kavindudodan/flagd for a preview

---------

Signed-off-by: Kavindu Dodanduwa <[email protected]>
Signed-off-by: Kavindu Dodanduwa <[email protected]>
Co-authored-by: Skye Gill <[email protected]>
Co-authored-by: Todd Baert <[email protected]>

protobuf/buf.md

@@ -1,20 +1,35 @@
 # Flagd build spec
 
-## This repository is managed by OpenFeature
+### Managed by [OpenFeature](https://github.com/open-feature). 
 
-This module contains the core types that developers can use for interacting with [flagd](https://github.com/open-feature/flagd).
+This repository contains grpc service definitions that developers can use for interacting with [flagd](https://github.com/open-feature/flagd).
 
-Internally flagd uses the connect protocol, meaning it is compatible with grpc interfaces. If your desired language has a supported plugin for generating connect stubs then it is recommended to use these over grpc.
+Given below are the modules exposed through this repository,
 
-The package contains a single `Service`, describing the 5 core `rpcs` for feature flag evaluation (`ResolveBoolean`, `ResolveString`, `ResolveFloat`, `ResolveInt` and `ResolveObject`) each with their type specific request and response objects(`ResolveXXXRequest` and `ResolveXXXResponse`).
-The final `rpc` on the `Service` is a streamed response named `EventStream`, this is used to pass internal events to the client, such as `configuration_change` and `provider_ready`.
+- [Flag evaluation](#Flag-evaluation)
+- [Flag sync](#Flag-sync)
 
-## Build options
+## Flag evaluation
 
-The core definitions are in the `schema.v1` package, and contains package name options for the following languages, as such these options may be excluded from build instructions:
+The module `schema.v1` contains a single `Service`, describing the 5 core `rpcs` for feature flag evaluation (`ResolveBoolean`,
+`ResolveString`, `ResolveFloat`, `ResolveInt` and `ResolveObject`), each with their type specific request and
+response objects (`ResolveXXXRequest` and `ResolveXXXResponse`). The final `rpc` on the `Service` is a streamed response
+named `EventStream`, this is used to pass internal events to the client, such as `configuration_change` and `provider_ready`.
+
+Internally, flagd uses the connect protocol, meaning it is compatible with grpc interfaces. If your desired language has 
+a supported plugin for generating connect stubs then it is recommended to use these over grpc.
+
+## Flag sync
+
+The module `sync.v1` is a grpc server streaming service definition to provide flagd with feature flag configurations.
+This service exposes a single method `SyncFlags`. Flagd acts as the client and initiates the streaming with `SyncFlagsRequest`.
+
+The server implementation will then stream feature flag configurations through `SyncFlagsResponse`. The response contains
+`SyncState` which can be utilized to provide flagd with flexible configuration updates.
+
+## Code generation
+
+Easiest way to generate grpc code for your language of choice is using provided [buf](https://buf.build/) templates.
+For example, with required binaries in your path, java code generation can be done using 
+`buf generate --template buf.gen.java.yaml` command.
 
-- Go:   schema/service/v1.0.0
-- Java: dev.openfeature.flagd.grpc
-- C#:   OpenFeature.Flagd.Grpc
-- PHP:  OpenFeature\\Providers\\Flagd\\Schema\\Grpc
-- Ruby: "OpenFeature::FlagD::Provider::Grpc"

protobuf/sync/v1/sync_service.proto

@@ -0,0 +1,52 @@
+syntax = "proto3";
+
+package sync.v1;
+
+option go_package = "flagd/grpcsync";
+
+// 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  provider (grpc client) initiating the request. The server implementations
+  // can utilize this identifier to aggregate flag configurations and stream them to a specific client. This identifier
+  // is intended to be optional. However server implementation may enforce it.
+  string provider_id = 1;
+}
+
+// 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;
+}
+
+// FlagService implements a server streaming to provide realtime flag configurations
+service FlagSyncService {
+  rpc SyncFlags(SyncFlagsRequest) returns (stream SyncFlagsResponse) {}
+}