Ruby API

6 minute readReference

type Rox

require 'rox/server/rox_server'
Rox::Server::RoxServer

The Rox class provides your application its primary interface with 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, flag settings, and configurations. It provides a mechanism through which you can use the feature flags to control your application’s behavior. It works with a RoxContainer 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 class 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

Rox::Server::RoxServer.setup("<ROLLOUT_KEY>"[, Rox::Server::RoxOptions]).join

Configures the Rox object to work with the provided application.

ParameterModifier and TypeDescription

apiKey

string

The environment key provided by the CloudBees Feature Management dashboard

options

RoxOptions (optional)

A RoxOptions instance with the desired configuration for this application

Returns

Thread that indicates when the SDK has received the configuration from the CloudBees Feature Management servers.

shutdown

Rox::Server::RoxServer.shutdown

Perform graceful shutdown of the Rox object; this will close and clean all background tasks and threads. Shutdown can only be used when Rox was successfully Setup; calling Shutdown when it’s 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

Rox::Server::RoxServer.register(container)
Rox::Server::RoxServer.register_with_namespace(namespace, container)

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. When using register, the container will not use namespace, meaning the flag names will not have a prefix. It is equal to register_with_namespace with empty string namespace.

ParameterModifier and TypeDescription

namespace

string

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

container

object

An object that contains your application’s feature flags

Example

Creating a new container and registering it:

require 'rox/server/rox_server'

class LoginContainer
  attr_accessor :include_github
  attr_accessor :include_facebook

  def initialize
    @include_github = Rox::Server::RoxFlag.new
    @include_facebook = Rox::Server::RoxFlag.new
  end
end

class SystemContainer
  attr_accessor :showNewUserScreen
  attr_accessor :useBulkFetch

  def initialize
    @showNewUserScreen = Rox::Server::RoxFlag.new
    @useBulkFetch = Rox::Server::RoxFlag.new
  end
end


login_container = LoginContainer.new
system_container = SystemContainer.new
Rox::Server::RoxServer.register_with_namespace('login', login_container)
Rox::Server::RoxServer.register(system_container)

The flag in the dashboard will have the names login.include_facebook, login.include_github, showNewUserScreen, and useBulkFetch. This is very handy if you want to have groups of flags and configuration.

set_custom_boolean_property

Rox::Server::RoxServer.set_custom_boolean_property(name, value = nil, &block)

Sets a custom boolean property on the Rox client. The value can either be a computed boolean, or a boolean.

ParameterModifier and TypeDescription

name

value

The name of the property to create

boolean

boolean

(context) → boolean

Example:

Creating a new container and registering it:

Rox::Server::RoxServer.set_custom_boolean_property('hasItemsInShoppingCart') do |context|
  context['shopping_cart'].empty?
end

set_custom_string_property

Rox::Server::RoxServer.set_custom_string_property(name, value = nil, &block)

Sets a custom string property on the Rox client. The value can either be a computed string, or a string.

ParameterModifier and TypeDescription

name

value

The name of the property to create

string

string

(context) → string

Example:

Creating a new container and registering it:

Rox::Server::RoxServer.set_custom_string_property('email') do |context|
  context['user'].email
end

set_custom_float_property

Rox::Server::RoxServer.set_custom_float_property(name, value = nil, &block)

Sets a custom float property on the Rox client. The value can either be a computed float, or a float.

ParameterModifier and TypeDescription

name

value

The name of the property to create

float

float

(context) → float

Example

Creating a new container and registering it:

Rox::Server::RoxServer.set_custom_float_property('height') do |context|
  context['user'].height
end

set_custom_int_property

Rox::Server::RoxServer.set_custom_int_property(name, value = nil, &block)

Sets a custom int property on the Rox client. The value can either be a computed int, or a int.

ParameterModifier and TypeDescription

name

value

The name of the property to create

int

int

(context) → int

Example

Creating a new container and registering it:

Rox::Server::RoxServer.set_custom_int_property('age') do |context|
  context['user'].age
end

set_custom_semver_property

Rox::Server::RoxServer.set_custom_semver_property(name, value = nil, &block)

Sets a custom semver property on the Rox client. The value can either be a computed semver, or a semver.

ParameterModifier and TypeDescription

name

value

The name of the property to create

string

string

(context) → string

Example

Creating a new container and registering it:

Rox::Server::RoxServer.set_custom_semver_property('ruby version', RUBY_VERSION)

Global Context

Rox::Server::RoxServer.context

Set a global context, this context will be available to all flags evaluations.

global_context = {'user': user}
Rox::Server::RoxServer.context = global_context

fetch

thread = Rox::Server::RoxServer.fetch

Create a network request for the latest configuration.

use_userspace_unhandled_error_handler

Rox::Server::RoxServer.use_userspace_unhandled_error_handler do |exception_source, exception_trigger, exception|
  # ...
end

A handler for all user function errors, which might help you debug and understand unexpected flag values. In case this function is not set, errors will be logged to the logger. Note: it is recommended to wrap all user methods with try-except in order to handle it while in the relevant context, and not afterward.

When invoking the user_unhandled_error_invoker, the arguments passed are the exception_source, exception_trigger and exception. The exception_source is the original handler that caused the exception.

The exception_trigger is an enum for the user to delegate the type.

class ExceptionTrigger
  DYNAMIC_PROPERTIES_RULE = 1
  CONFIGURATION_FETCHED_HANDLER = 2
  IMPRESSION_HANDLER = 3
  CUSTOM_PROPERTY_GENERATOR = 4
end

The exception is the exception which was originally raised.

type RoxOptions

Rox::Server::RoxOptions

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

Example

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

require 'rox/server/rox_server'
option = Rox::Server::RoxOptions.new(
      configuration_fetched_handler: configuration_fetched_handler,
      impression_handler: impression_handler,
      dynamic_property_rule_handler: dynamic_property_handler,
      logger: Logger.new,
      version: '2.0.0',
      fetch_interval: 120
    )

    Rox::Server::RoxServer.setup('<ROLLOUT_KEY>', option).join

version

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

fetch_interval

Set the polling interval for fetching configuration from the CloudBees Feature Management storage service (in seconds, default to 60, canot be set below 30).

logger

Set the Logger to be used for logging.

class Logger
    def debug(message, ex = nil)
      puts 'Before Rox.Setup', message
    end

    def error(message, ex = nil)
      puts 'Before Rox.Setup', message
    end

    def warn(message, ex = nil)
      puts 'Before Rox.Setup', message
    end
  end
  option = Rox::Server::RoxOptions.new(
    logger: Logger.new
  )

configuration_fetched_handler

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

proc do |configuration_fetcher_args|
  # ..
end

Properties of the argument to be passed into the configuration_fetched_handler.

PropertyDescription
fetcher_status

Enum indicating the fetch result, can be one of APPLIED_FROM_EMBEDDED, APPLIED_FROM_LOCAL_STORAGE, APPLIED_FROM_NETWORK, or ERROR_FETCHED_FAILED.

creation_date

The time the fetched configurations were created and signed.

error_details

Enum indicating which error occured while fetching and setting up the new configurations. Can be one of CORRUPTED_JSON, EMPTY_JSON, SIGNATURE_VERIFICATION_ERROR, NETWORK_ERROR, MISMATCH_APP_KEY, UNKNOWN, or NO_ERROR.

has_changes

A boolean indication (as opposed to a configuration change).

For an example, see Flag update flow.

impression_handler

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

proc do |impression_handler_args|
  # ..
end

Properties of the argument to be passed into the impression_handler.

PropertyDescription
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.)

For an example, see Impression handler.

dynamic_property_rule_handler

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

proc do |prop_name, context|
  # ..
end

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

Arguments to be passed into the dynamic_property_rule_handler.

PropertyDescription
prop_name

The property name request by the flag evaluation.

context

The context used to evaluate the flag.

type RoxFlag

require 'rox/server/flags/rox_flag'
Rox::Server::RoxFlag.new

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

enabled?

enabled?(context)

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

enabled

enabled(context){ || block } -> Void

Runs the block if flag is true.

disabled

disabled(context){ || block } -> Void

Runs the block if flag is false.

name

@name

The name of the Flag.

Class RoxString

require 'rox/server/rox_server'
Rox::Server::RoxString.new

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

require 'rox/server/rox_string'

class MyContainer
  attr_accessor :title_color

 def initialize
    @title_color = Rox::Server::RoxString.new('red', ['red', 'blue', 'green'])
  end
end

container = MyContainer.new

Rox::Server::RoxServer.register(container)
Rox::Server::RoxServer.setup('<ROLLOUT_KEY>').join

value

@value

Returns the RoxString’s value considering the context given.

name

@name

The name of the RoxString.

Class RoxInt

require 'rox/server/rox_int'

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

title_size_flag = Rox::Server::RoxInt.new(14, [14, 18, 24])

title_size = title_size_flag.value

value

flag.value(context = nil)

Returns the RoxInt’s value considering the given context.

Class RoxDouble

require 'rox/server/rox_double'

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

price_options_flag = Rox::Server::RoxDouble.new(19.99, [19.99, 29.99, 40.5])

price = price_options_flag.value

value

flag.value(context = nil)

Returns the RoxDouble’s value considering the given context.