Go API (4.9)

3 minute read

type Rox

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

The Rox instance provides your application with its primary interface for feature flags in the CloudBees Feature Management system. This is the central repository for your application’s flags. It handles communications with the server to obtain the latest values, implements experiment settings, and sets up configurations. It provides a mechanism through which you can use feature flags to control your application’s behavior. It works with a RoxContainer-derived object, which holds your application’s feature flags. The values contained in the provided container will be marked as feature flags and will appear in your application’s CloudBees Feature Management dashboard 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 struct{}
▼

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.

Register

Register(namespace string, 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

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.RoxFlag

}
▼

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/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
    },
  })
  rox = server.NewRox()


  <-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)
}
▼

ConfigurationFetchedHandler

Set the configuration event handler, to add actions after configurations are fetched.

ImpressionHandler

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

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);
▼

type RoxFlag

import  "github.com/rollout/rox-go/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/core/context"

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

Name

Name() string
▼

The name of the flag.

Class RoxVariant

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

RoxVariant is a feature flag object that can have values more complex than a simple boolean true or false. RoxVariant 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.NewRoxVariant("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 variant’s value considering the given context.

Name

Name() string
▼

The name of the Variant.

Context interface

import "github.com/rollout/rox-go/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() })
▼
Python API
Ruby API