Go API

5 minute readReference

The following information is for the latest version of the Go SDK. If you are running an older version, please check the CloudBees Feature Management - Go changelog for any differences.

type Rox

import  "github.com/rollout/rox-go/v5/server"
▼
server.NewRox()
▼

The Rox instance provides an interface for CloudBees Feature Management to manage feature flags that control the behavior of your application. This is the central repository for your application’s flags. This instance handles communications with the server to obtain the latest flag values, implement flag settings, and set up flag configurations. It works with a RoxContainer-derived object, which holds your application’s feature flags. The values in the provided container are marked as feature flags and display in the CloudBees Feature Management UI once the application is run.

This instance also allows you to manage custom properties. These can be static settings of type string, boolean, integer, or double, or, you can use a generator type to provide a custom property that is dependent upon code state.

You can also use a RoxOptions object to configure some aspects of this type. You can set the verbosity level, custom platform, global freeze level, impression handler, and fetch handler.

Setup

Setup(apiKey string, roxOptions model.RoxOptions) <-chan error
▼

Configures the Rox object to work with the provided application.

Parameter Modifier and Type Description

apiKey

string

The environment key provided by the dashboard

options

RoxOptions

A RoxOptions instance with the desired configuration for this application

Returns

Channel that indicates when the SDK has received the configuration from the CloudBees Feature Management servers if it signals nil or an error otherwise.

Shutdown

Shutdown() <-chan error
▼

Perform graceful shutdown of the Rox object; this will close and clean all background tasks and threads. Shutdown can only be used when Rox is Setup successfully. Calling Shutdown when it is not possible will result a log warning. You can call Setup again after Shutdown and right after Shutdown. All Register and SetCustomProperty will use new Rox, and will register the objects to the Dashboard on the next Setup call.

Register

Register(namespace string, roxContainer interface{})
▼
RegisterWithEmptyNamespace(roxContainer interface{})
▼

Registers a feature flag container with the Rox client. The public member variables of this container will become a flag in your CloudBees Feature Management dashboard and will be named with the object name.

Parameter Modifier and Type Description

namespace

string

The prefix namespace for all flags in this container (defaults to "")

container

interface

An object that contains your application’s feature flags

For example, assuming we have the following container:

type Container struct {
  IncludeFacebook server.RoxFlag
  IncludeGithub server.RoxString
}
▼

and we register the container with the following code:

var conf = &Container {
  IncludeFacebook: server.NewRoxFlag(false),
  IncludeGithub: server.NewRoxFlag(false)
}
Rox.Register("login", conf);
<-Rox.Setup(rolloutKey, nil);
▼

The flag and configuration in the dashboard will have the names login.IncludeFacebook and login.IncludeGithub. This is very handy if you want to have groups of flags and configuration.

If you don’t need a namespace, you can set the namespace to an empty string.

SetCustomComputedBooleanProperty

SetCustomComputedBooleanProperty(name string, value properties.CustomBooleanPropertyGenerator)
▼

Sets a computed boolean Custom Property on the Rox client. This is a computable boolean, with an object that generates the value for the property.

Parameter Modifier and Type Description

name

string

The name of the property to create

generator

properties.CustomBooleanPropertyGenerator

An instance of the boolean property’s generator type

SetCustomComputedFloatProperty

SetCustomComputedFloatProperty(name string, value properties.CustomFloatPropertyGenerator)
▼

Sets a computed float Custom Property on the Rox client. This is a computable float, with an object that generates the value for the property.

Parameter Modifier and Type Description

name

string

The name of the property to create

generator

properties.CustomFloatPropertyGenerator

An instance of the float property’s generator type

SetCustomComputedIntegerProperty

SetCustomComputedIntegerProperty(name string, value properties.CustomIntegerPropertyGenerator)
▼

Sets a computed integer Custom Property on the Rox client. This is a computable integer, with an object that generates the value for the property.

Parameter Modifier and Type Description

name

string

The name of the property to create

generator

properties.CustomIntegerPropertyGenerator

An instance of the integer property’s generator type

SetCustomComputedSemverProperty

SetCustomComputedSemverProperty(name string, value properties.CustomSemverPropertyGenerator)
▼

Sets a computed semantic-versioned string Custom Property on the Rox client. This is a computable semantically-versioned string, with an object that generates the value for the property.

Parameter Modifier and Type Description

name

string

The name of the property to create

generator

properties.CustomSemverPropertyGenerator

An instance of the sematically-versioned property’s generator type

SetCustomComputedStringProperty

SetCustomComputedStringProperty(name string, value properties.CustomStringPropertyGenerator)
▼

Sets a custom computed string property on the Rox client. This is a computable string, with an object that generates the value for the property.

Parameter Modifier and Type Description

name

string

The name of the property to create

generator

properties.CustomStringPropertyGenerator

An instance of the string property’s generator type

SetCustomBooleanProperty

SetCustomBooleanProperty(name string, value bool)
▼

Sets a Custom Property representing a boolean value.

Parameter Modifier and Type Description

name

string

The name of the custom property

value

bool

The value for the custom property

SetCustomFloatProperty

SetCustomFloatProperty(name string, value float64)
▼

Sets a custom property that can store a specified float value.

Parameter Modifier and Type Description

name

string

The property name

value

float64

The value of the property

SetCustomIntegerProperty

SetCustomIntegerProperty(name string, value int)
▼

Sets a custom property that can store a specified integer value.

Parameter Modifier and Type Description

name

string

The property name

value

int

The value of the property

SetCustomSemverProperty

SetCustomSemverProperty(name string, value string)
▼

Sets a custom property that uses a Semantic Version as its value. See https://semver.org/ for more information on Semantic Versioning.

Parameter Modifier and Type Description

name

string

The name of the property to create

value

string

The property value, formatted using the rules defined at semver.org

SetCustomStringProperty

SetCustomStringProperty(name string, value string)
▼

Sets a custom string property for the Rox client, which is a string property you can fetch by name.

Parameter Modifier and Type Description

name

string

The name of the property to create

value

string

The property’s value

SetContext

SetContext(ctx context.Context)
▼

Sets a global context. This context will be available to all flag evaluations.

Fetch

Fetch() <-chan struct{}
▼

Creates a network request for the latest configuration.

type RoxOptions

import  "github.com/rollout/rox-go/v5/server"
▼
server.NewRoxOptions()
▼

RoxOptions covers configuration options for the Rox client. This includes settings like the log verbosity. Instances of this type should be created using server.NewRoxOptions.

Example

Here is an example of setting up a new RoxOptions object. This options object sets the version, logger, impression handler, and fetch handler.

 options := server.NewRoxOptions(server.RoxOptionsBuilder{
    Logger:     &logger{},
    ConfigurationFetchedHandler: func(e *model.ConfigurationFetchedArgs) {
      if e != nil && e.FetcherStatus == model.FetcherStatusAppliedFromNetwork {
        TestVarsConfigurationFetchedCount      }
    },
    ImpressionHandler: func(e model.ImpressionArgs) {
      if e.ReportingValue != nil {
        if e.ReportingValue.Name == "FlagForImpression" {
          TestVarsIsImpressionRaised = true
        }
      }
      TestVarsImpressionReturnedArgs = &e
    },
    DynamicPropertyRuleHandler: func(e model.DynamicPropArgs) {
      if e.Context != nil {
        e.Context.Get(e.PropName)
      }
    }
  })
  rox = server.NewRox()


  err := <-rox.Setup("<Rollout_Key>", options)
▼

type RoxOptions.RoxOptionsBuilder

server.RoxOptionsBuilder{...}
▼

This Builder type is used to create a new RoxOptions instance.

Version

Set the version of the service running the CloudBees Feature Management SDK.

FetchInterval

Set the polling interval for fetching configuration from the CloudBees Feature Management storage service. The default time setting is 60 seconds, and the minimum setting is 30 seconds.

Logger

Set the Logger to be used for logging.

type logger struct {
}

func (*logger) Debug(message string, err interface{}) {
  fmt.Println("Debug:", message)
}

func (*logger) Warn(message string, err interface{}) {
    fmt.Println("Warn", message)
}

func (*logger) Error(message string, err interface{}) {
    fmt.Println("Error", message)
}
▼

ImpressionHandler

type ImpressionHandler = func(args ImpressionArgs)

type ImpressionArgs struct {
ReportingValue *ReportingValue
Context        context.Context
}

type ReportingValue struct {
	Name      string
	Value     string
	Targeting bool
}
▼

Set the impression event handler to add actions after an impression.

Arguments to be passed into the ImpressionHandler

Property Description 
reporting_value
▼

Object that contains Name (String), Value (String) and Targeting (boolean).

 
context
▼

The context in which the impression was called (this is a merged context containing the global context, and the call’s context).

DynamicPropertyRuleHandler

type DynamicPropertyRuleHandler = func(DynamicPropertyRuleHandlerArgs) interface{}

type DynamicPropertyRuleHandlerArgs struct {
	PropName string
	Context context.Context
}
▼

The Dynamic Custom Property Generator is called when an explicit Custom Property definiton does not exist on the client side.

If you do not set the DynamicPropertyRuleHandler, it will then activate the default method which tries to extract the property value from context.

   dynamicPropertyRuleHandler := func(e model.DynamicPropArgs) {
      if e.Context != nil {
        e.Context.Get(e.PropName)
      }
    }
▼

RoxyURL

A roxy URL (see Microservices automated testing and local development).

RoxContainer

The RoxContainer instance for your application will contain all of the feature flags for the features in your application. These feature flags are converted into CloudBees Feature Management flags when the container is registered with Rox using Register(namespace string, container interface{}). Feature flag names will be derived from the provided flag variable names.

For example, below is a quick example of how to use this container class:

var container = &Container {
  IncludeFacebook: server.NewRoxFlag(false),
  IncludeGithub: server.NewRoxFlag(false),
}
Rox.Register("login", conf);
<-Rox.Setup(rolloutKey, nil);
▼

RoxFlag

import  "github.com/rollout/rox-go/v5/server"
▼
server.NewRoxFlag
▼

RoxFlag is a boolean feature flag. It can be either true or false.

IsEnabled

IsEnabled(ctx context.Context) bool
▼

Returns true if the flag is enabled based on given context.

import "github.com/rollout/rox-go/v5/core/context"

ctx := context.NewContext(map[string]interface{}{"email": "[email protected]"})
flagImpressionValue := container.IncludeFacebook.IsEnabled(ctx)
▼

Name

Name() string
▼

The name of the flag.

RoxString

import  "github.com/rollout/rox-go/v5/server"
▼
func NewRoxString(defaultValue string, options []string) RoxString
▼

RoxString is a feature flag object that can have string values. RoxString accepts a list of possible values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for override via the dashboard.

Example

var container = &Container {
  Variant: server.NewRoxString("red", []string{"red", "blue", "green"})
}

ctx := context.NewContext(map[string]interface{}{"gender": "female"})
container.VariantWithContext.GetValue(ctx)
▼

GetValue

GetValue(context context.Context) string
▼

Returns the RoxString value considering the given context.

Name

Name() string
▼

The name of the RoxString.

RoxInt

import  "github.com/rollout/rox-go/v5/server"
▼
func NewRoxInt(defaultValue int, options []int) RoxInt
▼

RoxInt is a feature flag object that can have int values. RoxInt accepts a list of possible int values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for override via the dashboard.

Example

priceOptionsFlag := server.NewRoxInt(2, []int{3,4,5}, nil)
titleSize := priceOptionsFlag.GetInt()
▼

GetInt

GetInt(ctx context.Context)
▼

Returns the RoxInt’s value considering the given context.

RoxDouble

import  "github.com/rollout/rox-go/v5/server"
▼
func NewRoxDouble(defaultValue float64, options []float64) RoxInt
▼

RoxDouble is a feature flag object that can have double values. RoxDouble accepts a list of possible double values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for override via the dashboard.

Example

priceOptionsFlag := server.NewRoxDouble(19.99, []float64{20.99, 29.99, 40.5}, nil)

price := priceOptionsFlag.GetDouble()
▼

GetDouble

GetDouble(ctx context.Context)
▼

Returns the RoxDouble’s value considering the given context.

Context interface

import "github.com/rollout/rox-go/v5/core/context"
▼
context.NewContext
▼

The context object is used to pass data to the Flag when checking if the current flag is enabled or disabled. This object is used by the registered Custom Properties to evaluate the experiment expression and return the flag value.

You can create a context using the NewContext function by sending a map as the argument.

Example

someContext := context.NewContext(map[string]interface{}{"user": user})
▼

Get

Get(key string) interface{}
▼

This get function is used to retrieve data from the context.

For example, you can see how the SetComputedStringProperty is using the context to get the username.

 rox.SetCustomComputedBooleanProperty("hasItemsInShoppingCart", func(ctx context.Context) bool {
    value, _ := ctx.Get("shoppingCart").(*ShoppingCart)
    return value.IsEmpty() })
▼

DynamicAPI()

DynamicAPI()
▼

An alternative of using container with register. This allows you to evaluate flags without having a static container. DynamicApi will create flags as if they were registered, including sending them to the dashboard. See also Dynamic api.

IsEnabled

Evaluate a boolean flag.

IsEnabled(name string, defaultValue boolean, ctx context.Context);
▼

name

type

description

name

string

The flag’s name - throws an error if nil.

defaultValue

boolean

The default value to use if no dashboard configurations.

context

object

A context to evalute the flag with; will be merged with the global context.

Value

Evaluate a string flag

Value(name string, defaultValue string, options []string, ctx context.Context);
▼

name

type

description

name

string

The flag’s name - throws an error if nil.

defaultValue

string

The default value to use if no dashboard configurations, or value was set to default on dashboard throws an error if nil.

options

string[]

All alternative values to use on the dashboard (can be changed on the dashboard side).

context

object

A context to evalute the flag with, will be merged with the global context.

GetInt

Evaluate an int flag.

GetInt(name string, defaultValue int, options []int, ctx context.Context);
▼
name type description

name

string

The flag’s name - throws an error if none.

defaultValue

int

The default value to use if no dashboard configurations or value was set to default on dashboard.

variations

int[]

All alternative values to use on the dashboard (can be changed on the dashboard side).

context

object

A context to evalute the flag with; will be merged with the global context.

GetDouble

Evaluate a double flag

GetDouble(name string, defaultValue float64, options []float64, ctx context.Context);
▼
name type description

name

string

The flag’s name - throws an error if none.

defaultValue

double

The default value to use if no dashboard configurations or value was set to default on dashboard.

variations

double[]

All alternative values to use on the dashboard (can be changed on the dashboard side).

context

object

A context to evaluate the flag with; will be merged with the global context.
C# Client API
Java API