Skip to main content

Go SDK reference

note

This SDK works with Harness Self-Managed Enterprise Edition (on premises).

This topic describes how to use the Harness Feature Flags Go SDK for your Go application. 

For getting started quickly, you can use our sample code from the SDK README. You can also clone and run a sample application from the Go SDK GitHub Repository.

Before you begin

Make sure you read and understand:

Version

Latest SDK version can be found on GitHub Release Page

Requirements

To use this SDK, make sure you:

  • Starting with SDK version v0.1.21, Golang version 1.20 or later is required.
  • Earlier versions of the SDK require Golang versions newer than 1.6 but older than 1.19.
  • For installation details, please refer to Golang's official installation guide.

Install the SDK

Install the SDK using the following Go command:

go get github.com/harness/ff-golang-server-sdk

Import the SDK

Import the SDK using the following Go command: 

import harness "github.com/harness/ff-golang-server-sdk/client"

Initialize the SDK

To initialize the Go SDK, you need to:

  1. Add your Server SDK Key to connect to your Harness Environment.
  2. (Optional) Configure the SDK options. For more details on what features you can configure for this SDK, go to Configure the SDK.
  3. Complete the initialization by creating an instance of the Feature Flag client and  passing in the Server SDK Key and Configuration.
  4. Add a Target that you want to Evaluate against a Feature Flag.

Add the Server SDK Key

To connect to the correct Environment that you set up on the Harness Platform, you need to add the Server SDK Key from that Environment. Input the Server SDK Key into the sdkKey parameter. For example:

client, err := harness.NewCfClient(sdkKey)

Configure the SDK

You can configure the following features of the SDK:

NameExampleDescriptionDefault Value
baseUrlharness.WithURL("https://config.ff.harness.io/api/1.0")The URL used to fetch Feature Flag Evaluations. When using the Relay Proxy, change this to: http://localhost:7000https://config.ff.harness.io/api/1.0
eventUrlharness.WithEventsURL("https://events.ff.harness.io/api/1.0")The URL for posting metrics data to the Feature Flag service. When using the Relay Proxy, change this to: http://localhost:7000https://events.ff.harness.io/api/1.0
pollIntervalharness.WithPullInterval(60))The interval in seconds that we poll for changes when you are using stream mode.60 (seconds)
streamEnabledharness.WithStreamEnabled(false)Set to true to enable streaming mode.Set to false to disable streaming mode.true
analyticsEnabledharness.WithAnalyticsEnabled(false)Set to true to enable analytics.Set to false to disable analytics.Note: Analytics are not cached.true

For further configuration options and samples, such as configuring your logger or using the SDK with the Relay Proxy, go to Additional Options.

Complete the initialization

Complete  the initialization by creating an instance of the Feature Flag client and passing in the sdkKey, and any configuration options. For example:

// Create Options  
client, err := harness.NewCfClient(myApiKey, 
harness.WithURL("https://config.ff.harness.io/api/1.0"), 
harness.WithEventsURL("https://events.ff.harness.io/api/1.0"), 
harness.WithPullInterval(1),
harness.WithStreamEnabled(false))

Block initialization

By default, when initializing the Harness Feature Flags client, the initialization process is non-blocking. This means that the client creation call returns immediately, allowing your application to continue its startup process without waiting for the client to be fully initialized. If you evaluate a flag before the client has finished initializing, the default variation you provided can be returned as the evaluation result, because the SDK has not finished caching your remote Flag configuration stored in Harness.

You can choose to wait for the client to finish initializing before continuing. To achieve this, you can use the WithWaitForInitialized option, which blocks until the client is fully initialized. Example usage:

client, err := harness.NewCfClient(sdkKey, harness.WithWaitForInitialized(true))

if err != nil {
log.ErrorF("could not connect to FF servers %s", err)
}

result, err := client.BoolVariation("identifier_of_your_boolean_flag", &target, false)

In this example, WaitForInitialized blocks for up to 5 authentication attempts. If the client is not initialized within 5 authentication attempts, it returns an error.

This can be useful if you need to unblock after a certain time.

// Try to authenticate only 5 times before returning a result
client, err := harness.NewCfClient(sdkKey, harness.WithWaitForInitialized(true), harness.WithMaxAuthRetries(5))

if err != nil {
log.Fatalf("client did not initialize in time: %s", err)
}

Add a target

Details

What is a Target? Targets are used to control which users see which Variation of a Feature Flag, for example, if you want to do internal testing, you can enable the Flag for some users and not others. When creating a Target, you give it a name and a unique identifier. Often Targets are users but you can create a Target from anything that can be uniquely identified, such as an app or a machine.

For more information about Targets, go to Targeting Users With Flags.

To add a Target, build it and pass in arguments for the following:

ParameterDescriptionRequired?Example
IdentifierUnique ID for the Target.Read Regex requirements for Target names and identifiers below for accepted characters.RequiredIdentifier: "HT_1"
NameName for this Target. This does not have to be unique. Note: If you don’t provide a value, the name will be the same as the identifier.Read Regex requirements for Target names and identifiers below for accepted characters.OptionalNote: If you don't want to send a name, don't send the parameter. Sending an empty argument will cause an error.Name: "Harness_Target_1"
AttributesAdditional data you can store for a Target, such as email addresses or location.OptionalAttributes: &map[string]interface{}{"email":"demo@harness.io"},
Regex requirements for Target names and identifiers

Identifier

Regex: ^[A-Za-z0-9.@_-]*$
Must consist of only alphabetical characters, numbers, and the following symbols:
. (period)
@ (at sign)
-(dash)
_ (underscore)

The characters can be lowercase or uppercase but cannot include accented letters, for example Cafe_789.

Name Regex: ^[\\p{L}\\d .@_-]*$

Must consist of only alphabetical characters, numbers, and the following symbols:
. (period)
@ (at sign)
-(dash)
_ (underscore)
(space)

The characters can be lowercase or uppercase and can include accented letters, for example Café_123.

For example:

Create a Target

target2 := evaluation.Target{  
Identifier: "HT_1",
Name: "Harness_Target_1",
Attributes: &map[string]interface{}{"email":"demo@harness.io"},
}

Create a Target with the builder

If you create a Target with the builder, use Custom instead of Attributes.

target := dto.NewTargetBuilder("HT_1").  
Name("Harness_Target_1").
Custom("email", "demo@harness.io").
Build()

Evaluate a Flag

Evaluating a Flag is when the SDK processes all Flag rules and returns the correct Variation of that Flag for the Target you provide. 

If a matching Flag can’t be found, or the SDK can’t remotely fetch flags, the default value is returned. This will be indicated by:

  1. The SDK will log an info level log that the default variation was returned.
  2. Evaluation calls will return an error as well as the default variation that you can handle.

There are different methods for the different Variation types and for each method you need to pass in:

  • Identifier of the Flag you want to evaluate
  • The Target object you want to evaluate against
  • The default Variation

For example:

Evaluate a string Variation

client.StringVariation(flagName, &target, "default_string")

Evaluate a boolean Variation

showFeature, err := client.BoolVariation(featureFlagKey, &target, false)

Evaluate a number Variation

client.NumberVariation(flagName, &target, -1)

Evaluate a JSON Variation

client.JSONVariation(flagName, &target, types.JSON{"darkmode": false})
note

If you evaluate a feature flag when initialization fails, the default variation you provided is returned as the evaluation result.

Test Your App is Connected to Harness

When you receive a response showing the current status of your Feature Flag, go to the Harness Platform and toggle the Flag on and off. Then, check your app to verify if the Flag Variation displayed is updated with the Variation you toggled.

note

The SDK must run for at least 60 seconds before it sends metrics. Please ensure metrics have not been disabled in the SDK.

Close the SDK client

In most applications, you won't need to close the SDK client.

However, you should close the SDK client if:

  • Your application is about to terminate. Closing the client ensures that all associated resources are released.
  • You have determined that you do not need to evaluate flags again in your application lifecycle.
important

The SDK does not evaluate flags after the client is closed.

To close the SDK client:

  • Assuming you have initialized an SDK client instance named client, call the following function:

    client.close()

Additional options

Configure your logger

The SDK has a default logger, however, you can provide your own logger to the SDK by passing it in as a configuration option. 

For example, the following creates an instance of the logrus logger and passes it in as a configuration option:

logger := logrus.New()  
logger.SetLevel(logrus.ErrorLevel)

 // Create a feature flag client
client, err := harness.NewCfClient(sdkKey, harness.WithLogger(logger))

Use the Relay Proxy

When using your Feature Flag SDKs with a Harness Relay Proxy you need to change the default URL and events URL to http://localhost:7000 when initializing the SDK. For example:

client, err := harness.NewCfClient(apiKey,  
harness.WithURL("http://localhost:7000"),
harness.WithEventsURL("http://localhost:7000"))

Configure your HTTP Client

The SDK has a default HTTP client, however, you can provide your own HTTP client to the SDK by passing it in as a configuration option.

For example, the following creates an HTTP client using custom CAs for Harness Self-Managed Enterprise Edition (on premises).

// Create a custom TLS configuration
tlsConfig := &tls.Config{
RootCAs: certPool,
}

transport := &http.Transport{
TLSClientConfig: tlsConfig,
}

httpClient := http.Client{Transport: transport}
client, err := harness.NewCfClient(apiKey,
harness.WithEventsURL("https://ffserver:8003/api/1.0"),
harness.WithURL("https://ffserver:8003/api/1.0"),
harness.WithHTTPClient(&httpClient))

For a full example of providing custom CAs for Harness Self-Managed Enterprise Edition, see our TLS Example

Sample code for a Go application

Here is a sample code for integrating with the Go SDK:

package main  

 import (
"context"
"fmt"
"log"
"time"
 
harness "github.com/harness/ff-golang-server-sdk/client"
"github.com/harness/ff-golang-server-sdk/dto"
"github.com/sirupsen/logrus"
)

 const sdkKey = "your SDK key"

 const featureFlag = "harnessappdemodarkmode"

 func main() {

logger := logrus.New()
logger.SetLevel(logrus.ErrorLevel)

client, err := harness.NewCfClient(myApiKey, 
harness.WithURL("https://config.ff.harness.io/api/1.0"), 
harness.WithEventsURL("https://events.ff.harness.io/api/1.0”), 
harness.WithPullInterval(1),
harness.WithLogger(logger),
harness.WithStreamEnabled(false)
)

defer func() {
if err := client.Close(); err != nil {
log.Printf("error while closing client err: %v", err)
}
}()

if err != nil {
log.Printf("could not connect to CF servers %v", err)
}

target := dto.NewTargetBuilder("HT_1").
Name("Harness_Target_1").
Custom("email", "demo@harness.io").
Build()

ctx, cancel := context.WithCancel(context.Background())

  go func() {
for {
select {
case <-ctx.Done():
return
default:
showFeature, err := client.BoolVariation(featureFlag, &target, false)

  if err != nil {
fmt.Printf("Error getting value: %v", err)
}

  fmt.Printf("KeyFeature flag '%s' is %t for this user\n", featureFlag, showFeature)
time.Sleep(10 * time.Second)
}
}
}()

  time.Sleep(5 * time.Minute)
cancel()
}

Troubleshooting

The SDK logs the following codes for certain lifecycle events, for example authentication, which can aid troubleshooting.

CodeDescriptionLog Level
1000Successfully initializedInfo
1001Failed to initialize due to authentication errorError
1002Failed to initialize due to a missing or empty API keyError
1003WaitForInitialization configuration option was provided and the SDK is waiting for initialization to finishInfo
2000Successfully authenticatedInfo
2001Authentication failed with a non-recoverable errorError
2002Authentication failed and is retryingWarn
2003Authentication failed and max retries have been exceededError
3000SDK closingInfo
3001SDK closed successfullyInfo
4000Polling service startedInfo
4001Polling service stoppedInfo
5000Streaming connectedInfo
5001Streaming disconnectedWarn
5002Streaming event receivedDebug
5003Streaming disconnected and is retrying to connectInfo
5004Streaming service stoppedInfo
6000Evaluation was successfulDebug
6001Evaluation failed and the default value was returnedInfo
7000Metrics service has startedInfo
7001Metrics service has stoppedInfo
7002Metrics posting failedWarn
7003Metrics posting successDebug
7004Metrics max target size exceededWarn
7007Metrics max evaluation size reachedWarn