gRPC

The ConfigCat Proxy can communicate over gRPC, an open-source, high-performance RPC framework with client support in several languages.

To establish gRPC connections, you'll need the protobuf and the gRPC service definition. It's required to generate clients with protoc for your desired platform.

flag_service.proto

syntax = "proto3";

package configcat;

import "google/protobuf/empty.proto";

// Service that contains feature flag evaluation procedures.
service FlagService {
  // Stream for getting notified when a feature flag's value changes.
  rpc EvalFlagStream(EvalRequest) returns (stream EvalResponse) {}
  // Stream for getting notified when any feature flag's value changes.
  rpc EvalAllFlagsStream(EvalRequest) returns (stream EvalAllResponse) {}

  // Evaluates a feature flag.
  rpc EvalFlag(EvalRequest) returns (EvalResponse) {}
  // Evaluates each feature flag.
  rpc EvalAllFlags(EvalRequest) returns (EvalAllResponse) {}
  // Requests the keys of each feature flag.
  rpc GetKeys(KeysRequest) returns (KeysResponse) {}
  // Commands the underlying SDK to refresh its evaluation data.
  rpc Refresh(RefreshRequest) returns (google.protobuf.Empty) {}
}

// Feature flag evaluation request message.
message EvalRequest {
  // The SDK identifier.
  string sdk_id = 1;
  // The feature flag's key to evaluate.
  string key = 2;
  // The user object.
  map<string, string> user = 3;
}

// Feature flag evaluation response message.
message EvalResponse {
  // The evaluated value.
  oneof value {
    int32 int_value = 1;
    double double_value = 2;
    string string_value = 3;
    bool bool_value = 4;
  }
  // The variation ID.
  string variation_id = 5;
}

// Response message that contains the evaluation result of each feature flag.
message EvalAllResponse {
  // The evaluated value of each feature flag.
  map<string, EvalResponse> values = 1;
}

// Request message for getting each available feature flag's key.
message KeysRequest {
  // The SDK identifier.
  string sdk_id = 1;
}

// Response message that contains each available feature flag's key.
message KeysResponse {
  // The keys of each feature flag.
  repeated string keys = 1;
}

// Request message for the given SDK to refresh its evaluation data.
message RefreshRequest {
  // The SDK identifier.
  string sdk_id = 1;
}

In order to secure the gRPC communication with the Proxy, set up TLS.

Client Usage

The following example uses a generated Go client, but gRPC clients generated for other languages are working as well.

example.go

opts := []grpc.DialOption{
    grpc.WithBlock(),
    grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{
        // Any TLS options
    })),
}

conn, err := grpc.DialContext(context.Background(), 
    "localhost:50051", // Proxy host and gRPC port
    opts...)
if err != nil {
    panic(err)
}

defer func() {
    _ = conn.Close()
}()

client := proto.NewFlagServiceClient(conn)

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

resp, err := client.EvalFlag(ctx, &proto.EvalRequest{
    SdkId: "my_sdk", 
    Key: "<flag-key>", 
    User: map[string]string{"Identifier": "<user-id>"}
})
if err != nil {
    panic(err)
}

fmt.Printf("Evaluation result: %v", resp.GetBoolValue())

Available Options

The following gRPC related options are available:

YAML

options.yml

grpc:
  enabled: <true|false>
  port: 50051
  log:
    level: "<error|warn|info|debug>"

Environment variables

CONFIGCAT_GRPC_ENABLED=<true|false>
CONFIGCAT_GRPC_PORT=50051
CONFIGCAT_GRPC_LOG_LEVEL="<error|warn|info|debug>"

Here's the explanation for each option:

Option	Default	Description
YAML grpc: enabled: <true|false> Environment variable CONFIGCAT_GRPC_ENABLED=<true|false>	true	Enables or disables the ability to communicate with the Proxy through gRPC.
YAML grpc: port: 50051 Environment variable CONFIGCAT_GRPC_PORT=50051	50051	The port used for gRPC communication.
YAML grpc: log: level: "<error|warn|info|debug>" Environment variable CONFIGCAT_GRPC_LOG_LEVEL="<error|warn|info|debug>"	warn	The verbosity of the gRPC related logs. Possible values: error, warn, info or debug.