v5.0.0-beta.2

[5.0.0-beta.2] - 2020-07-03

This beta release is being made available for testing and user feedback, due to the large number of changes from Go SDK 4.x. Features are still subject to change in the final 5.0.0 release. API documentation for this version is at https://pkg.go.dev/gopkg.in/launchdarkly/go-server-sdk.v5@v5.0.0-beta.2 and https://pkg.go.dev/gopkg.in/launchdarkly/go-sdk-common.v2@v2.0.0-beta.2.

This is a major rewrite that introduces a cleaner API design, adds new features, and makes the SDK code easier to maintain and extend. See the Go 4.x to 5.0 migration guide for an in-depth look at the changes in this version; the following is a summary.

Added:

• You can tell the SDK to notify you whenever a feature flag's configuration has changed (either in general, or in terms of its result for a specific user), using LDClient.GetFlagTracker().
• You can monitor the status of the SDK's data source (which normally means the streaming connection to the LaunchDarkly service) with LDClient.GetDataSourceStatusProvider(). This allows you to check the current connection status, and to be notified if this status changes.
• You can monitor the status of a persistent data store with LDClient.GetDataStoreStatusProvider(). This allows you to check whether database updates are succeeding, to be notified if this status changes, and to get caching statistics.
• LDConfig.Logging is a new configuration category for options related to logging. See ldcomponents.Logging().

Changed (breaking changes from 4.x):

• The User and UserBuilder types are now in the package gopkg.in/launchdarkly/go-sdk-common.v2/lduser. Users can no longer be created as inline structs; you must use lduser.NewUser, lduser.NewAnonymousUser, or lduser.NewUserBuilder.
• The EvaluationDetail and EvaluationReason types are now in the package gopkg.in/launchdarkly/go-sdk-common.v2/ldreason.
• EvaluationReason is now a struct rather than an interface, and is just one type rather than having separate types for each Kind.
• The ldlog.Loggers abstraction is now in the package gopkg.in/launchdarkly/go-sdk-common.v2/ldlog.
• Configuration properties that are specific to one mode of operation are no longer represented as fields in Config, but as builder methods on a component that is provided by the new ldcomponents package and is then placed in Config. For instance, instead of setting Capacity: 1000, you would now set Events: ldcomponents.SendEvents().Capacity(1000); to disable events, instead of setting SendEvents: false, you would set Events: ldcomponents.NoEvents() (note that NoEvents does not allow you to set Capacity, since that would be meaningless if events are disabled). Similarly, to disable streaming and use polling, set DataSource: ldcomponents.PollingDataSource() which then provides optional methods for configuring polling. See Config and ldcomponents for more details.
• The redis package has been renamed to ldredis.
• The integrations in ldconsul, lddynamodb, ldredis, and ldfiledata now use a builder pattern (like the rest of the SDK component configurations) instead of a factory function with option arguments. For instance, you would write ldredis.DataSource().URL("redis://host").Prefix("prefix") instead of redis.NewRedisDataStoreFactory(redis.URL("redis://host"), redis.Prefix("prefix")).
• The component interfaces FeatureStore and UpdateProcessor have been renamed to DataStore and DataSource. The factory interfaces for these components now receive SDK configuration options in a different way that does not expose other components' configurations to each other.
• The PersistentDataStore interface for creating your own database integrations has been simplified by moving all of the serialization and caching logic into the main SDK code.
• FeatureFlag, Segment, and other data model types are now in the package gopkg.in/launchdarkly/go-server-sdk-evaluation.v1. Application code will not normally need to refer to these types.
• All types related to the low-level handling of analytics events are now in the package gopkg.in/launchdarkly/go-sdk-events.v1. Application code will not normally need to refer to these types.

Changed (requirements/dependencies/build):

• The lowest supported Go version is 1.13.
• The SDK is now a Go module. If you are not using modules yet, and are managing dependencies with another tool such as dep or govendor, you will still be able to import the SDK the same as before; however, be aware that it now has several dependent repositories (all under gopkg.in/launchdarkly), so whenever you update to a newer version of the SDK you may need to update those as well—the SDK cannot specify its own preferred dependency versions unless you use modules.
• Code coverage reports and benchmarks are now generated in every build. Unit test coverage of the entire SDK codebase has been greatly improved.

Changed (behavioral changes):

• If analytics events are disabled, the SDK now avoids generating any analytics event objects internally. Previously they were created and then discarded, causing unnecessary heap churn.
• Network failures and server errors for streaming or polling requests were previously logged at ERROR level in most cases but sometimes at WARN level. They are now all at WARN level, but with a new behavior: if connection failures continue without a successful retry for a certain amount of time, the SDK will log a special ERROR-level message to warn you that this is not just a brief outage. The amount of time is one minute by default, but can be changed with the new LogDataSourceOutageAsErrorAfter option in LoggingConfigurationBuilder.
• Improved the performance of flag evaluations when there is a very long user target list in a feature flag or user segment, by representing the user key collection internally as a map.
• Evaluation of rules involving regex matches, date/time values, and semantic versions, has been speeded up by pre-parsing the values in the rules. Also, parsing of date/time values and semantic versions in user attributes now uses a faster implementation and does not make any heap allocations.
• Evaluation of rules involving an equality match to multiple values (such as "name is one of X, Y, Z") has been speeded up by converting the list of values to a map.
• Many internal methods have been rewritten to reduce the number of heap allocations in general.

Removed:

• DefaultConfig was removed since it is no longer necessary: an empty Config{} is valid and will provide all of the documented default behavior. If you need to access the default value for a property, use the corresponding constant, such as ldcomponents.DefaultEventsCapacity.
• The sharedtest subpackage, which contains test helpers for the SDK itself, is now internal and cannot be used from application code. Test helpers that were meant to be public are now in the testhelpers subpackage.
• Removed all types, fields, and methods that were deprecated as of the most recent 4.x release.