ldclient.go

package ldclient

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"errors"
	"fmt"
	"log"
	"os"
	"reflect"
	"strings"
	"time"
)

const Version = "3.1.0"

// The LaunchDarkly client. Client instances are thread-safe.
// Applications should instantiate a single instance for the lifetime
// of their application.
type LDClient struct {
	sdkKey          string
	config          Config
	eventProcessor  *eventProcessor
	updateProcessor UpdateProcessor
	store           FeatureStore
}

type Logger interface {
	Println(...interface{})
	Printf(string, ...interface{})
}

// Exposes advanced configuration options for the LaunchDarkly client.
type Config struct {
	BaseUri               string
	StreamUri             string
	EventsUri             string
	Capacity              int
	FlushInterval         time.Duration
	SamplingInterval      int32
	PollInterval          time.Duration
	Logger                Logger
	Timeout               time.Duration
	Stream                bool
	FeatureStore          FeatureStore
	UseLdd                bool
	SendEvents            bool
	Offline               bool
	AllAttributesPrivate  bool
	PrivateAttributeNames []string
	UpdateProcessor       UpdateProcessor
}

// The minimum value for Config.PollInterval. If you specify a smaller interval,
// the minimum will be used instead.
const MinimumPollInterval = 30 * time.Second

type UpdateProcessor interface {
	Initialized() bool
	Close()
	Start(closeWhenReady chan<- struct{})
}

// Provides the default configuration options for the LaunchDarkly client.
// The easiest way to create a custom configuration is to start with the
// default config, and set the custom options from there. For example:
//   var config = DefaultConfig
//   config.Capacity = 2000
var DefaultConfig = Config{
	BaseUri:       "https://app.launchdarkly.com",
	StreamUri:     "https://stream.launchdarkly.com",
	EventsUri:     "https://events.launchdarkly.com",
	Capacity:      1000,
	FlushInterval: 5 * time.Second,
	PollInterval:  MinimumPollInterval,
	Logger:        log.New(os.Stderr, "[LaunchDarkly]", log.LstdFlags),
	Timeout:       3000 * time.Millisecond,
	Stream:        true,
	FeatureStore:  nil,
	UseLdd:        false,
	SendEvents:    true,
	Offline:       false,
}

var ErrInitializationTimeout = errors.New("Timeout encountered waiting for LaunchDarkly client initialization")
var ErrClientNotInitialized = errors.New("Feature flag evaluation called before LaunchDarkly client initialization completed")

// Creates a new client instance that connects to LaunchDarkly with the default configuration. In most
// cases, you should use this method to instantiate your client. The optional duration parameter allows callers to
// block until the client has connected to LaunchDarkly and is properly initialized.
func MakeClient(sdkKey string, waitFor time.Duration) (*LDClient, error) {
	return MakeCustomClient(sdkKey, DefaultConfig, waitFor)
}

// Creates a new client instance that connects to LaunchDarkly with a custom configuration. The optional duration parameter allows callers to
// block until the client has connected to LaunchDarkly and is properly initialized.
func MakeCustomClient(sdkKey string, config Config, waitFor time.Duration) (*LDClient, error) {
	closeWhenReady := make(chan struct{})

	config.BaseUri = strings.TrimRight(config.BaseUri, "/")
	config.EventsUri = strings.TrimRight(config.EventsUri, "/")
	if config.PollInterval < MinimumPollInterval {
		config.PollInterval = MinimumPollInterval
	}

	if config.FeatureStore == nil {
		config.FeatureStore = NewInMemoryFeatureStore(config.Logger)
	}

	client := LDClient{
		sdkKey: sdkKey,
		config: config,
		store:  config.FeatureStore,
	}

	if config.Offline {
		config.Logger.Println("Started LaunchDarkly in offline mode")
		client.config.SendEvents = false
		return &client, nil
	}

	client.eventProcessor = newEventProcessor(sdkKey, config)

	if config.UseLdd {
		config.Logger.Println("Started LaunchDarkly in LDD mode")
		return &client, nil
	}

	requestor := newRequestor(sdkKey, config)

	if config.UpdateProcessor != nil {
		client.updateProcessor = config.UpdateProcessor
	} else if config.Stream {
		client.updateProcessor = newStreamProcessor(sdkKey, config, requestor)
	} else {
		config.Logger.Println("You should only disable the streaming API if instructed to do so by LaunchDarkly support")
		client.updateProcessor = newPollingProcessor(config, requestor)
	}
	client.updateProcessor.Start(closeWhenReady)
	timeout := time.After(waitFor)
	for {
		select {
		case <-closeWhenReady:
			config.Logger.Println("Successfully initialized LaunchDarkly client!")
			return &client, nil
		case <-timeout:
			if waitFor > 0 {
				config.Logger.Println("Timeout exceeded when initializing LaunchDarkly client.")
				return &client, ErrInitializationTimeout
			}

			go func() { <-closeWhenReady }() // Don't block the UpdateProcessor when not waiting
			return &client, nil
		}
	}
}

func (client *LDClient) Identify(user User) error {
	if client.IsOffline() {
		return nil
	}
	if user.Key == nil || *user.Key == "" {
		client.config.Logger.Printf("WARN: Identify called with empty/nil user key!")
	}
	evt := NewIdentifyEvent(user)
	return client.eventProcessor.sendEvent(evt)
}

// Tracks that a user has performed an event. Custom data can be attached to the
// event, and is serialized to JSON using the encoding/json package (http://golang.org/pkg/encoding/json/).
func (client *LDClient) Track(key string, user User, data interface{}) error {
	if client.IsOffline() {
		return nil
	}
	if user.Key == nil || *user.Key == "" {
		client.config.Logger.Printf("WARN: Track called with empty/nil user key!")
	}
	evt := NewCustomEvent(key, user, data)
	return client.eventProcessor.sendEvent(evt)
}

// Returns whether the LaunchDarkly client is in offline mode.
func (client *LDClient) IsOffline() bool {
	return client.config.Offline
}

func (client *LDClient) SecureModeHash(user User) string {
	if user.Key == nil {
		return ""
	}
	key := []byte(client.sdkKey)
	h := hmac.New(sha256.New, key)
	h.Write([]byte(*user.Key))
	return hex.EncodeToString(h.Sum(nil))
}

// Returns whether the LaunchDarkly client is initialized.
func (client *LDClient) Initialized() bool {
	return client.IsOffline() || client.config.UseLdd || client.updateProcessor.Initialized()
}

// Shuts down the LaunchDarkly client. After calling this, the LaunchDarkly client
// should no longer be used.
func (client *LDClient) Close() {
	client.config.Logger.Println("Closing LaunchDarkly Client")
	if client.IsOffline() {
		return
	}
	client.eventProcessor.close()
	if !client.config.UseLdd {
		client.updateProcessor.Close()
	}
}

// Immediately flushes queued events.
func (client *LDClient) Flush() {
	if client.IsOffline() {
		return
	}
	client.eventProcessor.flush()
}

// Returns a map from feature flag keys to values for
// a given user. If the result of the flag's evaluation would
// result in the default value, `nil` will be returned. This method
// does not send analytics events back to LaunchDarkly
func (client *LDClient) AllFlags(user User) map[string]interface{} {
	if client.IsOffline() {
		client.config.Logger.Println("WARN: Called AllFlags in offline mode. Returning nil map")
		return nil
	}

	if !client.Initialized() {
		if client.store.Initialized() {
			client.config.Logger.Println("WARN: Called AllFlags before client initialization; using last known values from feature store")
		} else {
			client.config.Logger.Println("WARN: Called AllFlags before client initialization. Feature store not available; returning nil map")
			return nil
		}
	}

	if user.Key == nil {
		client.config.Logger.Println("WARN: Called AllFlags with nil user key. Returning nil map")
		return nil
	}

	results := make(map[string]interface{})

	items, err := client.store.All(Features)

	if err != nil {
		client.config.Logger.Println("WARN: Unable to fetch flags from feature store. Returning nil map. Error: " + err.Error())
		return nil
	}
	for _, item := range items {
		if flag, ok := item.(*FeatureFlag); ok {
			result, _ := client.evalFlag(*flag, user)
			results[flag.Key] = result
		}
	}

	return results
}

func (client *LDClient) evalFlag(flag FeatureFlag, user User) (interface{}, []FeatureRequestEvent) {
	var prereqEvents []FeatureRequestEvent
	if flag.On {
		evalResult, err := flag.EvaluateExplain(user, client.store)
		prereqEvents = evalResult.PrerequisiteRequestEvents

		if err != nil {
			return nil, prereqEvents
		}

		if evalResult.Value != nil {
			return evalResult.Value, prereqEvents
		}
		// If the value is nil, but the error is not, fall through and use the off variation
	}

	if flag.OffVariation != nil && *flag.OffVariation < len(flag.Variations) {
		value := flag.Variations[*flag.OffVariation]
		return value, prereqEvents
	}
	return nil, prereqEvents
}

// Returns the value of a boolean feature flag for a given user. Returns defaultVal if
// there is an error, if the flag doesn't exist, the client hasn't completed initialization,
// or the feature is turned off.
func (client *LDClient) BoolVariation(key string, user User, defaultVal bool) (bool, error) {
	value, err := client.variation(key, user, defaultVal, reflect.TypeOf(bool(true)))
	result, _ := value.(bool)
	return result, err
}

// Deprecated: Use BoolVariation().
func (client *LDClient) Toggle(key string, user User, defaultVal bool) (bool, error) {
	client.config.Logger.Println("WARN: Deprecated Toggle() called on LDClient. Use BoolVariation() instead.")
	return client.BoolVariation(key, user, defaultVal)
}

// Returns the value of a feature flag (whose variations are integers) for the given user.
// Returns defaultVal if there is an error, if the flag doesn't exist, or the feature is turned off.
func (client *LDClient) IntVariation(key string, user User, defaultVal int) (int, error) {
	value, err := client.variation(key, user, float64(defaultVal), reflect.TypeOf(float64(0)))
	result, _ := value.(float64)
	return int(result), err
}

// Returns the value of a feature flag (whose variations are floats) for the given user.
// Returns defaultVal if there is an error, if the flag doesn't exist, or the feature is turned off.
func (client *LDClient) Float64Variation(key string, user User, defaultVal float64) (float64, error) {
	value, err := client.variation(key, user, defaultVal, reflect.TypeOf(float64(0)))
	result, _ := value.(float64)
	return result, err
}

// Returns the value of a feature flag (whose variations are strings) for the given user.
// Returns defaultVal if there is an error, if the flag doesn't exist, or the feature is turned off.
func (client *LDClient) StringVariation(key string, user User, defaultVal string) (string, error) {
	value, err := client.variation(key, user, defaultVal, reflect.TypeOf(string("string")))
	result, _ := value.(string)
	return result, err
}

// Returns the value of a feature flag (whose variations are JSON) for the given user.
// Returns defaultVal if there is an error, if the flag doesn't exist, or the feature is turned off.
func (client *LDClient) JsonVariation(key string, user User, defaultVal json.RawMessage) (json.RawMessage, error) {
	if client.IsOffline() {
		return defaultVal, nil
	}
	value, version, err := client.Evaluate(key, user, defaultVal)

	if err != nil {
		client.sendFlagRequestEvent(key, user, defaultVal, defaultVal, version)
		return defaultVal, err
	}
	valueJsonRawMessage, err := ToJsonRawMessage(value)
	if err != nil {
		client.sendFlagRequestEvent(key, user, defaultVal, defaultVal, version)
		return defaultVal, err
	}
	client.sendFlagRequestEvent(key, user, valueJsonRawMessage, defaultVal, version)
	return valueJsonRawMessage, nil
}

// Generic method for evaluating a feature flag for a given user. The type of the returned interface{}
// will always be expectedType or the actual defaultValue will be returned.
func (client *LDClient) variation(key string, user User, defaultVal interface{}, expectedType reflect.Type) (interface{}, error) {
	if client.IsOffline() {
		return defaultVal, nil
	}
	value, version, err := client.Evaluate(key, user, defaultVal)
	if err != nil {
		client.sendFlagRequestEvent(key, user, defaultVal, defaultVal, version)
		return defaultVal, err
	}

	valueType := reflect.TypeOf(value)
	if expectedType != valueType {
		client.sendFlagRequestEvent(key, user, defaultVal, defaultVal, version)
		return defaultVal, fmt.Errorf("Feature flag returned value: %+v of incompatible type: %+v; Expected: %+v", value, valueType, expectedType)
	}
	client.sendFlagRequestEvent(key, user, value, defaultVal, version)
	return value, nil
}

func (client *LDClient) sendFlagRequestEvent(key string, user User, value, defaultVal interface{}, version *int) error {
	if client.IsOffline() {
		return nil
	}
	evt := NewFeatureRequestEvent(key, user, value, defaultVal, version, nil)
	return client.eventProcessor.sendEvent(evt)
}

func (client *LDClient) Evaluate(key string, user User, defaultVal interface{}) (interface{}, *int, error) {
	if user.Key == nil {
		return defaultVal, nil, fmt.Errorf("User.Key cannot be nil for user: %+v when evaluating flag: %s", user, key)
	}
	if *user.Key == "" {
		client.config.Logger.Printf("WARN: User.Key is blank when evaluating flag: %s. Flag evaluation will proceed, but the user will not be stored in LaunchDarkly.", key)
	}

	var feature *FeatureFlag
	var storeErr error
	var ok bool

	if !client.Initialized() {
		if client.store.Initialized() {
			client.config.Logger.Printf("WARN: Feature flag evaluation called before LaunchDarkly client initialization completed; using last known values from feature store")
		} else {
			return defaultVal, nil, ErrClientNotInitialized
		}
	}

	data, storeErr := client.store.Get(Features, key)

	if storeErr != nil {
		client.config.Logger.Printf("Encountered error fetching feature from store: %+v", storeErr)
		return defaultVal, nil, storeErr
	}

	if data != nil {
		feature, ok = data.(*FeatureFlag)
		if !ok {
			return defaultVal, nil, fmt.Errorf("Unexpected data type (%T) found in store for feature key: %s. Returning default value.", data, key)
		}
	} else {
		return defaultVal, nil, fmt.Errorf("Unknown feature key: %s Verify that this feature key exists. Returning default value.", key)
	}

	result, prereqEvents := client.evalFlag(*feature, user)
	if !client.IsOffline() {
		for _, event := range prereqEvents {
			err := client.eventProcessor.sendEvent(event)
			if err != nil {
				client.config.Logger.Printf("WARN: Error sending feature request event to LaunchDarkly: %+v", err)
			}
		}
	}
	if result != nil {
		return result, &feature.Version, nil
	}
	return defaultVal, &feature.Version, nil
}