From 0fc2d0a683fe4ceb7e67c0960008c9069a765de5 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Wed, 10 Apr 2024 09:49:01 -0400 Subject: [PATCH] fix: submodules and doc (#1280) Remove references to old protos, update `/schemas` submodule. The old protos were still being used to generate the doc. I've updated them. Also, the `schemas` submodule was set to some very old version, I couldn't even run the live docs for that reason. I've updated it to the latest release of that module. --------- Signed-off-by: Todd Baert --- Makefile | 2 +- docs/concepts/syncs.md | 2 +- docs/reference/specifications/protos.md | 123 +++++++++++++----------- schemas | 2 +- 4 files changed, 69 insertions(+), 60 deletions(-) diff --git a/Makefile b/Makefile index 7676510a9..e4b4bf2cc 100644 --- a/Makefile +++ b/Makefile @@ -117,7 +117,7 @@ pull-schemas-submodule: .PHONY: generate-proto-docs generate-proto-docs: pull-schemas-submodule - docker run --rm -v ${PWD}/$(DOCS_DIR)/reference/specifications:/out -v ${PWD}/schemas/protobuf:/protos pseudomuto/protoc-gen-doc --doc_opt=markdown,protos-with-toc.md schema/v1/schema.proto sync/v1/sync_service.proto \ + docker run --rm -v ${PWD}/$(DOCS_DIR)/reference/specifications:/out -v ${PWD}/schemas/protobuf:/protos pseudomuto/protoc-gen-doc --doc_opt=markdown,protos-with-toc.md flagd/evaluation/v1/evaluation.proto flagd/sync/v1/sync.proto \ && echo '' > ${PWD}/$(DOCS_DIR)/reference/specifications/protos.md \ && sed '/^## Table of Contents/,/#top/d' ${PWD}/$(DOCS_DIR)/reference/specifications/protos-with-toc.md >> ${PWD}/$(DOCS_DIR)/reference/specifications/protos.md \ && rm -f ${PWD}/$(DOCS_DIR)/reference/specifications/protos-with-toc.md diff --git a/docs/concepts/syncs.md b/docs/concepts/syncs.md index 0e9ca007e..572b7ec88 100644 --- a/docs/concepts/syncs.md +++ b/docs/concepts/syncs.md @@ -39,7 +39,7 @@ See [sync source](../reference/sync-configuration.md#source-configuration) confi ### gRPC sync The gRPC sync provider streams flag definitions from a gRPC sync provider implementation. -This stream connection is defined by the [sync service protobuf definition](https://github.com/open-feature/schemas/blob/main/protobuf/sync/v1/sync_service.proto). +This stream connection is defined by the [sync service protobuf definition](https://github.com/open-feature/flagd-schemas/blob/main/protobuf/flagd/sync/v1/sync.proto). ```shell flagd start --uri grpc://grpc-sync-source diff --git a/docs/reference/specifications/protos.md b/docs/reference/specifications/protos.md index 9979bc366..99066fd62 100644 --- a/docs/reference/specifications/protos.md +++ b/docs/reference/specifications/protos.md @@ -3,7 +3,7 @@ -## schema/v1/schema.proto +## flagd/evaluation/v1/evaluation.proto Flag evaluation API This proto forms the basis of a flag-evaluation API. @@ -11,7 +11,7 @@ It supports single and bulk evaluation RPCs, and flags of various types, as well It supports the inclusion of a "context" with each evaluation, which may contain arbitrary attributes relevant to flag evaluation. - + ### AnyFlag A variant type flag response. @@ -31,7 +31,7 @@ A variant type flag response. - + ### EventStreamRequest Empty stream request body @@ -41,7 +41,7 @@ Empty stream request body - + ### EventStreamResponse Response body for the EventStream stream response @@ -57,7 +57,7 @@ Response body for the EventStream stream response - + ### ResolveAllRequest Request body for bulk flag evaluation, used by the ResolveAll rpc. @@ -72,7 +72,7 @@ Request body for bulk flag evaluation, used by the ResolveAll rpc. - + ### ResolveAllResponse Response body for bulk flag evaluation, used by the ResolveAll rpc. @@ -80,14 +80,14 @@ Response body for bulk flag evaluation, used by the ResolveAll rpc. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| flags | [ResolveAllResponse.FlagsEntry](#schema-v1-ResolveAllResponse-FlagsEntry) | repeated | Object structure describing the evaluated flags for the provided context. | +| flags | [ResolveAllResponse.FlagsEntry](#flagd-evaluation-v1-ResolveAllResponse-FlagsEntry) | repeated | Object structure describing the evaluated flags for the provided context. | - + ### ResolveAllResponse.FlagsEntry @@ -96,14 +96,14 @@ Response body for bulk flag evaluation, used by the ResolveAll rpc. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | key | [string](#string) | | | -| value | [AnyFlag](#schema-v1-AnyFlag) | | | +| value | [AnyFlag](#flagd-evaluation-v1-AnyFlag) | | | - + ### ResolveBooleanRequest Request body for boolean flag evaluation, used by the ResolveBoolean rpc. @@ -119,7 +119,7 @@ Request body for boolean flag evaluation, used by the ResolveBoolean rpc. - + ### ResolveBooleanResponse Response body for boolean flag evaluation. used by the ResolveBoolean rpc. @@ -137,7 +137,7 @@ Response body for boolean flag evaluation. used by the ResolveBoolean rpc. - + ### ResolveFloatRequest Request body for float flag evaluation, used by the ResolveFloat rpc. @@ -153,7 +153,7 @@ Request body for float flag evaluation, used by the ResolveFloat rpc. - + ### ResolveFloatResponse Response body for float flag evaluation. used by the ResolveFloat rpc. @@ -171,7 +171,7 @@ Response body for float flag evaluation. used by the ResolveFloat rpc. - + ### ResolveIntRequest Request body for int flag evaluation, used by the ResolveInt rpc. @@ -187,7 +187,7 @@ Request body for int flag evaluation, used by the ResolveInt rpc. - + ### ResolveIntResponse Response body for int flag evaluation. used by the ResolveInt rpc. @@ -205,7 +205,7 @@ Response body for int flag evaluation. used by the ResolveInt rpc. - + ### ResolveObjectRequest Request body for object flag evaluation, used by the ResolveObject rpc. @@ -221,7 +221,7 @@ Request body for object flag evaluation, used by the ResolveObject rpc. - + ### ResolveObjectResponse Response body for object flag evaluation. used by the ResolveObject rpc. @@ -241,7 +241,7 @@ NOTE: This structure will need to be decoded from google/protobuf/struct.proto b - + ### ResolveStringRequest Request body for string flag evaluation, used by the ResolveString rpc. @@ -257,7 +257,7 @@ Request body for string flag evaluation, used by the ResolveString rpc. - + ### ResolveStringResponse Response body for string flag evaluation. used by the ResolveString rpc. @@ -281,44 +281,44 @@ Response body for string flag evaluation. used by the ResolveString rpc. - + ### Service Service defines the exposed rpcs of flagd | Method Name | Request Type | Response Type | Description | | ----------- | ------------ | ------------- | ------------| -| ResolveAll | [ResolveAllRequest](#schema-v1-ResolveAllRequest) | [ResolveAllResponse](#schema-v1-ResolveAllResponse) | | -| ResolveBoolean | [ResolveBooleanRequest](#schema-v1-ResolveBooleanRequest) | [ResolveBooleanResponse](#schema-v1-ResolveBooleanResponse) | | -| ResolveString | [ResolveStringRequest](#schema-v1-ResolveStringRequest) | [ResolveStringResponse](#schema-v1-ResolveStringResponse) | | -| ResolveFloat | [ResolveFloatRequest](#schema-v1-ResolveFloatRequest) | [ResolveFloatResponse](#schema-v1-ResolveFloatResponse) | | -| ResolveInt | [ResolveIntRequest](#schema-v1-ResolveIntRequest) | [ResolveIntResponse](#schema-v1-ResolveIntResponse) | | -| ResolveObject | [ResolveObjectRequest](#schema-v1-ResolveObjectRequest) | [ResolveObjectResponse](#schema-v1-ResolveObjectResponse) | | -| EventStream | [EventStreamRequest](#schema-v1-EventStreamRequest) | [EventStreamResponse](#schema-v1-EventStreamResponse) stream | | +| ResolveAll | [ResolveAllRequest](#flagd-evaluation-v1-ResolveAllRequest) | [ResolveAllResponse](#flagd-evaluation-v1-ResolveAllResponse) | | +| ResolveBoolean | [ResolveBooleanRequest](#flagd-evaluation-v1-ResolveBooleanRequest) | [ResolveBooleanResponse](#flagd-evaluation-v1-ResolveBooleanResponse) | | +| ResolveString | [ResolveStringRequest](#flagd-evaluation-v1-ResolveStringRequest) | [ResolveStringResponse](#flagd-evaluation-v1-ResolveStringResponse) | | +| ResolveFloat | [ResolveFloatRequest](#flagd-evaluation-v1-ResolveFloatRequest) | [ResolveFloatResponse](#flagd-evaluation-v1-ResolveFloatResponse) | | +| ResolveInt | [ResolveIntRequest](#flagd-evaluation-v1-ResolveIntRequest) | [ResolveIntResponse](#flagd-evaluation-v1-ResolveIntResponse) | | +| ResolveObject | [ResolveObjectRequest](#flagd-evaluation-v1-ResolveObjectRequest) | [ResolveObjectResponse](#flagd-evaluation-v1-ResolveObjectResponse) | | +| EventStream | [EventStreamRequest](#flagd-evaluation-v1-EventStreamRequest) | [EventStreamResponse](#flagd-evaluation-v1-EventStreamResponse) stream | | - +

Top

-## sync/v1/sync_service.proto +## flagd/sync/v1/sync.proto 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. - + ### FetchAllFlagsRequest -FetchAllFlagsRequest is the request to fetch all flags. Flagd sends this request as the client in order to resync its internal state +FetchAllFlagsRequest is the request to fetch all flags. Clients send this request as the client in order to resync their internal state | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| provider_id | [string](#string) | | 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 | +| provider_id | [string](#string) | | Optional: A unique identifier for clients 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 | | selector | [string](#string) | | 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' | @@ -326,7 +326,7 @@ FetchAllFlagsRequest is the request to fetch all flags. Flagd sends this request - + ### FetchAllFlagsResponse FetchAllFlagsResponse is the server response containing feature flag configurations @@ -341,10 +341,36 @@ FetchAllFlagsResponse is the server response containing feature flag configurati - + + +### GetMetadataRequest +GetMetadataRequest is the request for retrieving metadata from the sync service + + + + + + + + +### GetMetadataResponse +GetMetadataResponse contains metadata from the sync service + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| metadata | [google.protobuf.Struct](#google-protobuf-Struct) | | | + + + + + + + ### SyncFlagsRequest -SyncFlagsRequest is the request initiating the sever-streaming rpc. Flagd sends this request, acting as the client +SyncFlagsRequest is the request initiating the server-streaming rpc. +Implementations of Flagd providers and Flagd itself send this request, acting as the client. | Field | Type | Label | Description | @@ -357,7 +383,7 @@ SyncFlagsRequest is the request initiating the sever-streaming rpc. Flagd sends - + ### SyncFlagsResponse SyncFlagsResponse is the server response containing feature flag configurations and the state @@ -366,7 +392,6 @@ SyncFlagsResponse is the server response containing feature flag configurations | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | flag_configuration | [string](#string) | | flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/schemas/main/json/flagd-definitions.json | -| state | [SyncState](#sync-v1-SyncState) | | State conveying the operation to be performed by flagd. See the descriptions of SyncState for an explanation of supported values | @@ -374,37 +399,21 @@ SyncFlagsResponse is the server response containing feature flag configurations - - - -### SyncState -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 - -| Name | Number | Description | -| ---- | ------ | ----------- | -| SYNC_STATE_UNSPECIFIED | 0 | Value is ignored by the listening flagd | -| SYNC_STATE_ALL | 1 | 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_ADD | 2 | Convey an addition of a flag. Flagd internally handles this by combining new flags with existing ones | -| SYNC_STATE_UPDATE | 3 | 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_DELETE | 4 | Convey a deletion of a flag. Flagd internally removes the flag | -| SYNC_STATE_PING | 5 | Optional server ping to check client connectivity. Handling is ignored by flagd and is to merely support live check | - - - + ### FlagSyncService FlagService implements a server streaming to provide realtime flag configurations | Method Name | Request Type | Response Type | Description | | ----------- | ------------ | ------------- | ------------| -| SyncFlags | [SyncFlagsRequest](#sync-v1-SyncFlagsRequest) | [SyncFlagsResponse](#sync-v1-SyncFlagsResponse) stream | | -| FetchAllFlags | [FetchAllFlagsRequest](#sync-v1-FetchAllFlagsRequest) | [FetchAllFlagsResponse](#sync-v1-FetchAllFlagsResponse) | | +| SyncFlags | [SyncFlagsRequest](#flagd-sync-v1-SyncFlagsRequest) | [SyncFlagsResponse](#flagd-sync-v1-SyncFlagsResponse) stream | | +| FetchAllFlags | [FetchAllFlagsRequest](#flagd-sync-v1-FetchAllFlagsRequest) | [FetchAllFlagsResponse](#flagd-sync-v1-FetchAllFlagsResponse) | | +| GetMetadata | [GetMetadataRequest](#flagd-sync-v1-GetMetadataRequest) | [GetMetadataResponse](#flagd-sync-v1-GetMetadataResponse) | | diff --git a/schemas b/schemas index 43d5d0a3d..4b44704e4 160000 --- a/schemas +++ b/schemas @@ -1 +1 @@ -Subproject commit 43d5d0a3dd0be2c56cb3fa2dceca2c8daff0e0aa +Subproject commit 4b44704e447468fd74d8e95830627ce23b6ef16f