reforge

package module
v0.2.4-0...-e49c057 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 3, 2025 License: MIT Imports: 12 Imported by: 0

README

sdk-go

Go SDK for Reforge Feature Flags and Config as a Service: https://www.reforge.com

Installation

go get github.com/ReforgeHQ/sdk-go@latest

Basic example

package main

import (
	"fmt"
	"log"
	"os"

	reforge "github.com/ReforgeHQ/sdk-go"
)

func main() {
	sdkKey, exists := os.LookupEnv("REFORGE_SDK_KEY")

	if !exists {
		log.Fatal("SDK Key not found")
	}

	client, err := reforge.NewSdk(reforge.WithSdkKey(sdkKey))

	if err != nil {
		log.Fatal(err)
	}

	val, ok, err := client.GetStringValue("my.string.config", *reforge.NewContextSet())

	if err != nil {
		log.Fatal(err)
	}

	if !ok {
		log.Fatal("Value not found")
	}

	fmt.Println(val)
}

Documentation

Publishing

Automated Release Process

  1. On feature branch: Run ./scripts/prepare-release.sh v1.0.0

    • Updates internal/version.go with new version
    • Commits the version bump

  2. Create PR and merge to main

  3. Automatic: GitHub Actions will detect version change and:

    • Create git tag (e.g., v1.0.0)
    • Create GitHub release
    • Make version available: go get github.com/ReforgeHQ/sdk-go@v1.0.0
Manual Process (if needed)
  1. Bump version in internal/version.go (this is the version header clients send)
  2. Commit that change on a branch and merge into main
  3. git tag with the new version number and push that to origin

Documentation

Overview

Package reforge provides a client for fetching configuration and feature flags from the Reforge API.

Index

Constants

View Source 
const (
	// ReturnError will return an error when checking config/flag values if initialization times out
	ReturnError optionsPkg.OnInitializationFailure = optionsPkg.ReturnError
	// ReturnNilMatch will continue (generally returning a zero value, ok=false result) if initialization times out
	ReturnNilMatch optionsPkg.OnInitializationFailure = optionsPkg.ReturnNilMatch
)

Variables

View Source 
var ContextTelemetryMode = optionsPkg.ContextTelemetryModes

Functions

func ExtractValue 

func ExtractValue(cv *prefabProto.ConfigValue) (any, bool, error)

ExtractValue extracts the underlying value from a ConfigValue. You're unlikely to need this method.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the Prefab client

func NewSdk 

func NewSdk(opts ...Option) (*Client, error)

NewSdk creates a new Reforge SDK. It takes options as arguments (e.g. WithSdkKey)

func (*Client) FeatureIsOn 

func (c *Client) FeatureIsOn(key string, contextSet ContextSet) (result bool, wasFound bool)

FeatureIsOn returns a bool indicating if a feature is on for a given key and context. It will default to false if the key does not exist.

func (*Client) GetBoolValue 

func (c *Client) GetBoolValue(key string, contextSet ContextSet) (value bool, ok bool, err error)

GetBoolValue returns a bool value for a given key and context

func (*Client) GetBoolValueWithDefault 

func (c *Client) GetBoolValueWithDefault(key string, contextSet ContextSet, defaultValue bool) (value bool, wasFound bool)

GetBoolValueWithDefault returns a bool value for a given key and context, with a default value if the key does not exist

func (*Client) GetConfig 

func (c *Client) GetConfig(key string) (*prefabProto.Config, bool)

GetConfig returns a Config object for a given key. You're unlikely to need this method.

func (*Client) GetConfigMatch 

func (c *Client) GetConfigMatch(key string, contextSet ContextSet) (*ConfigMatch, error)

GetConfigMatch returns a ConfigMatch object for a given key and context. You're unlikely to need this method.

func (*Client) GetDurationValue 

func (c *Client) GetDurationValue(key string, contextSet ContextSet) (value time.Duration, ok bool, err error)

GetDurationValue returns a duration value for a given key and context

func (*Client) GetDurationWithDefault 

func (c *Client) GetDurationWithDefault(key string, contextSet ContextSet, defaultValue time.Duration) (value time.Duration, wasFound bool)

GetDurationWithDefault returns a duration value for a given key and context, with a default value if the key does not exist

func (*Client) GetFloatValue 

func (c *Client) GetFloatValue(key string, contextSet ContextSet) (value float64, ok bool, err error)

GetFloatValue returns a float value for a given key and context

func (*Client) GetFloatValueWithDefault 

func (c *Client) GetFloatValueWithDefault(key string, contextSet ContextSet, defaultValue float64) (value float64, wasFound bool)

GetFloatValueWithDefault returns a float value for a given key and context, with a default value if the key does not exist

func (*Client) GetInstanceHash 

func (c *Client) GetInstanceHash() string

GetInstanceHash returns the instance hash for the client

func (*Client) GetIntValue 

func (c *Client) GetIntValue(key string, contextSet ContextSet) (value int64, ok bool, err error)

GetIntValue returns an int value for a given key and context

func (*Client) GetIntValueWithDefault 

func (c *Client) GetIntValueWithDefault(key string, contextSet ContextSet, defaultValue int64) (value int64, wasFound bool)

GetIntValueWithDefault returns an int value for a given key and context, with a default value if the key does not exist

func (*Client) GetJSONValue 

func (c *Client) GetJSONValue(key string, contextSet ContextSet) (value interface{}, ok bool, err error)

GetJSONValue returns a JSON value for a given key and context

func (*Client) GetJSONValueWithDefault 

func (c *Client) GetJSONValueWithDefault(key string, contextSet ContextSet, defaultValue interface{}) (value interface{}, wasFound bool)

GetJSONValueWithDefault returns a JSON value for a given key and context, with a default value if the key does not exist

func (*Client) GetLogLevelStringValue 

func (c *Client) GetLogLevelStringValue(key string, contextSet ContextSet) (result string, ok bool, err error)

GetLogLevelStringValue returns a string value for a given key and context, representing a log level.

func (*Client) GetStringSliceValue 

func (c *Client) GetStringSliceValue(key string, contextSet ContextSet) (value []string, ok bool, err error)

GetStringSliceValue returns a string slice value for a given key and context

func (*Client) GetStringSliceValueWithDefault 

func (c *Client) GetStringSliceValueWithDefault(key string, contextSet ContextSet, defaultValue []string) (value []string, wasFound bool)

GetStringSliceValueWithDefault returns a string slice value for a given key and context, with a default value if the key does not exist

func (*Client) GetStringValue 

func (c *Client) GetStringValue(key string, contextSet ContextSet) (value string, ok bool, err error)

GetStringValue returns a string value for a given key and context

func (*Client) GetStringValueWithDefault 

func (c *Client) GetStringValueWithDefault(key string, contextSet ContextSet, defaultValue string) (value string, wasFound bool)

GetStringValueWithDefault returns a string value for a given key and context, with a default value if the key does not exist

func (*Client) Keys 

func (c *Client) Keys() ([]string, error)

Keys returns a list of all keys in the config store

func (*Client) SendTelemetry 

func (c *Client) SendTelemetry(waitOnQueueToDrain bool) error

SendTelemetry sends telemetry data to the Prefab Cloud API. If waitOnQueueToDrain is true, the method will block until the telemetry queue is empty. You likely don't want to waitOnQueueToDrain in a production environment unless you're shutting down and confident you're not further enqueueing telemetry.

func (*Client) WithContext 

func (c *Client) WithContext(contextSet *ContextSet) *ContextBoundClient

WithContext returns a new ContextBoundClient bound to the provided context (merged with the parent context)

type ClientInterface 

type ClientInterface interface {
	GetIntValue(key string, contextSet ContextSet) (int64, bool, error)
	GetBoolValue(key string, contextSet ContextSet) (bool, bool, error)
	GetStringValue(key string, contextSet ContextSet) (string, bool, error)
	GetFloatValue(key string, contextSet ContextSet) (float64, bool, error)
	GetStringSliceValue(key string, contextSet ContextSet) ([]string, bool, error)
	GetDurationValue(key string, contextSet ContextSet) (time.Duration, bool, error)
	GetIntValueWithDefault(key string, contextSet ContextSet, defaultValue int64) (int64, bool)
	GetBoolValueWithDefault(key string, contextSet ContextSet, defaultValue bool) (bool, bool)
	GetStringValueWithDefault(key string, contextSet ContextSet, defaultValue string) (string, bool)
	GetFloatValueWithDefault(key string, contextSet ContextSet, defaultValue float64) (float64, bool)
	GetStringSliceValueWithDefault(key string, contextSet ContextSet, defaultValue []string) ([]string, bool)
	GetDurationWithDefault(key string, contextSet ContextSet, defaultValue time.Duration) (time.Duration, bool)
	GetLogLevelStringValue(key string, contextSet ContextSet) (string, bool, error)
	GetJSONValue(key string, contextSet ContextSet) (interface{}, bool, error)
	GetJSONValueWithDefault(key string, contextSet ContextSet, defaultValue interface{}) (interface{}, bool)
	GetConfigMatch(key string, contextSet ContextSet) (*ConfigMatch, error)
	GetConfig(key string) (*prefabProto.Config, bool)
	FeatureIsOn(key string, contextSet ContextSet) (bool, bool)
	WithContext(contextSet *ContextSet) *ContextBoundClient
	GetInstanceHash() string
}

ClientInterface is the interface for the Prefab client

type ConfigMatch 

type ConfigMatch = internal.ConfigMatch

ConfigMatch represents a match between a config/flag key and a context. It has internal fields that are used by the client to determine the final value and report telemetry.

type ConfigStoreGetter 

type ConfigStoreGetter interface {
	GetConfig(key string) (config *prefabProto.Config, exists bool)
	Keys() []string
	ContextValueGetter
	ProjectEnvIDSupplier
}

ConfigStoreGetter defines the interface for custom config stores that can be plugged into the SDK. This allows external systems to provide config data without going through the standard API sources.

type ContextBoundClient 

type ContextBoundClient struct {
	// contains filtered or unexported fields
}

ContextBoundClient is a Client bound to a specific context. Any calls to the client will use the context provided.

func (*ContextBoundClient) FeatureIsOn 

func (c *ContextBoundClient) FeatureIsOn(key string, contextSet contexts.ContextSet) (result bool, wasFound bool)

FeatureIsOn returns a bool indicating if a feature is on for a given key and context. It will default to false if the key does not exist.

func (*ContextBoundClient) GetBoolValue 

func (c *ContextBoundClient) GetBoolValue(key string, contextSet contexts.ContextSet) (value bool, ok bool, err error)

GetBoolValue returns a bool value for a given key and context

func (*ContextBoundClient) GetBoolValueWithDefault 

func (c *ContextBoundClient) GetBoolValueWithDefault(key string, contextSet contexts.ContextSet, defaultValue bool) (value bool, wasFound bool)

GetBoolValueWithDefault returns a bool value for a given key and context, with a default value if the key does not exist

func (*ContextBoundClient) GetConfig 

func (c *ContextBoundClient) GetConfig(key string) (*prefabProto.Config, bool)

GetConfig returns a Config object for a given key. You're unlikely to need this method.

func (*ContextBoundClient) GetConfigMatch 

func (c *ContextBoundClient) GetConfigMatch(key string, contextSet ContextSet) (*ConfigMatch, error)

GetConfigMatch returns a ConfigMatch object for a given key and context. You're unlikely to need this method.

func (*ContextBoundClient) GetDurationValue 

func (c *ContextBoundClient) GetDurationValue(key string, contextSet contexts.ContextSet) (value time.Duration, ok bool, err error)

GetDurationValue returns a duration value for a given key and context

func (*ContextBoundClient) GetDurationWithDefault 

func (c *ContextBoundClient) GetDurationWithDefault(key string, contextSet contexts.ContextSet, defaultValue time.Duration) (value time.Duration, wasFound bool)

GetDurationWithDefault returns a duration value for a given key and context, with a default value if the key does not exist

func (*ContextBoundClient) GetFloatValue 

func (c *ContextBoundClient) GetFloatValue(key string, contextSet contexts.ContextSet) (value float64, ok bool, err error)

GetFloatValue returns a float value for a given key and context

func (*ContextBoundClient) GetFloatValueWithDefault 

func (c *ContextBoundClient) GetFloatValueWithDefault(key string, contextSet contexts.ContextSet, defaultValue float64) (value float64, wasFound bool)

GetFloatValueWithDefault returns a float value for a given key and context, with a default value if the key does not exist

func (*ContextBoundClient) GetInstanceHash 

func (c *ContextBoundClient) GetInstanceHash() string

GetInstanceHash returns the instance hash for the client

func (*ContextBoundClient) GetIntValue 

func (c *ContextBoundClient) GetIntValue(key string, contextSet contexts.ContextSet) (value int64, ok bool, err error)

GetIntValue returns an int value for a given key and context

func (*ContextBoundClient) GetIntValueWithDefault 

func (c *ContextBoundClient) GetIntValueWithDefault(key string, contextSet contexts.ContextSet, defaultValue int64) (value int64, wasFound bool)

GetIntValueWithDefault returns an int value for a given key and context, with a default value if the key does not exist

func (*ContextBoundClient) GetJSONValue 

func (c *ContextBoundClient) GetJSONValue(key string, contextSet contexts.ContextSet) (value interface{}, ok bool, err error)

GetJSONValue returns a JSON value for a given key and context

func (*ContextBoundClient) GetJSONValueWithDefault 

func (c *ContextBoundClient) GetJSONValueWithDefault(key string, contextSet contexts.ContextSet, defaultValue interface{}) (value interface{}, wasFound bool)

GetJSONValueWithDefault returns a JSON value for a given key and context, with a default value if the key does not exist

func (*ContextBoundClient) GetLogLevelStringValue 

func (c *ContextBoundClient) GetLogLevelStringValue(key string, contextSet contexts.ContextSet) (value string, ok bool, err error)

GetLogLevelStringValue returns a string value for a given key and context, representing a log level.

func (*ContextBoundClient) GetStringSliceValue 

func (c *ContextBoundClient) GetStringSliceValue(key string, contextSet contexts.ContextSet) (value []string, ok bool, err error)

GetStringSliceValue returns a string slice value for a given key and context

func (*ContextBoundClient) GetStringSliceValueWithDefault 

func (c *ContextBoundClient) GetStringSliceValueWithDefault(key string, contextSet contexts.ContextSet, defaultValue []string) (value []string, wasFound bool)

GetStringSliceValueWithDefault returns a string slice value for a given key and context, with a default value if the key does not exist

func (*ContextBoundClient) GetStringValue 

func (c *ContextBoundClient) GetStringValue(key string, contextSet contexts.ContextSet) (value string, ok bool, err error)

GetStringValue returns a string value for a given key and context

func (*ContextBoundClient) GetStringValueWithDefault 

func (c *ContextBoundClient) GetStringValueWithDefault(key string, contextSet contexts.ContextSet, defaultValue string) (value string, wasFound bool)

GetStringValueWithDefault returns a string value for a given key and context, with a default value if the key does not exist

func (*ContextBoundClient) SendTelemetry 

func (c *ContextBoundClient) SendTelemetry(waitOnQueueToDrain bool) error

SendTelemetry sends telemetry data to the Prefab Cloud API. If waitOnQueueToDrain is true, the method will block until the telemetry queue is empty. You likely don't want to waitOnQueueToDrain in a production environment unless you're shutting down and confident you're not further enqueueing telemetry.

func (*ContextBoundClient) WithContext 

func (c *ContextBoundClient) WithContext(contextSet *ContextSet) *ContextBoundClient

WithContext returns a new ContextBoundClient bound to the provided context (merged with the parent context)

type ContextSet 

type ContextSet = contexts.ContextSet

ContextSet is a set of NamedContext

func NewContextSet 

func NewContextSet() *ContextSet

NewContextSet creates a new ContextSet

type ContextValueGetter 

type ContextValueGetter interface {
	GetContextValue(propertyName string) (value interface{}, valueExists bool)
}

ContextValueGetter provides access to context values by property name

type NamedContext 

type NamedContext = contexts.NamedContext

NamedContext is a named context. It is used to provide context to the client about the current user/machine/etc.

type Option 

type Option func(*options.Options) error

Option is a function that modifies the options for the prefab client.

func WithAPIURLs 

func WithAPIURLs(apiURL []string) Option

WithAPIURLs sets the API URLs for the prefab client.

You likely will never need to use this option.

func WithAllTelemetryDisabled 

func WithAllTelemetryDisabled() Option

func WithCollectEvaluationSummaries 

func WithCollectEvaluationSummaries(collect bool) Option

WithCollectEvaluationSummaries sets whether the client should collect evaluation summaries.

The default is true

func WithConfigs 

func WithConfigs(configs map[string]interface{}) Option

WithConfigs lets you provide a map of configs to the prefab client to aid in testing. This is not compatible with other sources. 

configs := map[string]interface{}{
	"string.key": "value",
	"int.key":    int64(42),
	"bool.key":   true,
	"float.key":  3.14,
	"slice.key":  []string{"a", "b", "c"},
	"json.key": map[string]interface{}{
		"nested": "value",
	},
}

client, err := reforge.NewSdk(reforge.WithConfigs(configs))

func WithContextTelemetryMode 

func WithContextTelemetryMode(mode options.ContextTelemetryMode) Option

WithContextTelemetryMode sets the context telemetry mode for the prefab client.

func WithCustomStore 

func WithCustomStore(store ConfigStoreGetter) Option

WithCustomStore adds a custom config store to the SDK. The store must implement the ConfigStoreGetter interface. Custom stores are checked first, before other config sources.

Example: 

type MyConfigStore struct{}
func (s *MyConfigStore) GetConfig(key string) (*prefabProto.Config, bool) { ... }
func (s *MyConfigStore) Keys() []string { ... }
func (s *MyConfigStore) GetContextValue(propertyName string) (interface{}, bool) { ... }
func (s *MyConfigStore) GetProjectEnvID() int64 { ... }

client, err := reforge.NewSdk(reforge.WithCustomStore(&MyConfigStore{}))

func WithGlobalContext 

func WithGlobalContext(globalContext *ContextSet) Option

WithGlobalContext sets the global context for the prefab client.

func WithInitializationTimeoutSeconds 

func WithInitializationTimeoutSeconds(timeoutSeconds float64) Option

WithInitializationTimeoutSeconds sets the initialization timeout for the prefab client. After this time, the client will either raise or continue depending on the OnInitializationFailure option.

func WithOfflineSources 

func WithOfflineSources(sources []string) Option

WithOfflineSources allows providing customthe sources for the prefab client. Using this option will exclude the default (API + SSE) sources.

Do not use this option if you are using the standard API or SSE sources. Example: 

client, err := reforge.NewSdk(
	reforge.WithProjectEnvID(projectEnvID),
	reforge.WithOfflineSources([]string{
		"datafile://" + fileName,
	}))

func WithOnInitializationFailure 

func WithOnInitializationFailure(onInitializationFailure options.OnInitializationFailure) Option

WithOnInitializationFailure sets the behavior for the prefab client when initialization fails.

The default behavior is to return an error when a GetConfig (or similar) call is made (reforge.ReturnError).

If you want to ignore the error and continue, use reforge.ReturnNilMatch.

func WithProjectEnvID 

func WithProjectEnvID(projectEnvID int64) Option

WithProjectEnvID sets the project environment ID for the prefab client. You only need to set this if you are using a config dump source.

func WithSdkKey 

func WithSdkKey(sdkKey string) Option

WithSdkKey sets the SDK key for the prefab client.

func WithSources 

func WithSources(sources []string, excludeDefault bool) Option

WithSources allows providing custom sources for the prefab client to use. This prepends your sources to the default sources (API + SSE).

func WithTelemetryHost 

func WithTelemetryHost(host string) Option

WithTelemetryHost sets the host to which the client will send telemetry data. You likely will never need to use this option.

func WithTelemetrySyncInterval 

func WithTelemetrySyncInterval(interval time.Duration) Option

WithTelemetrySyncInterval sets the interval at which the client will send telemetry data to the server.

type ProjectEnvIDSupplier 

type ProjectEnvIDSupplier interface {
	GetProjectEnvID() int64
}

ProjectEnvIDSupplier provides access to the project environment ID

Source Files

View all Source files

Directories

Path Synopsis
anyhelpers
contexts
integration_test_support
mocks
options
semver
sse
stores
telemetry
testutils
utils

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.