5.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/[email protected] and https://pkg.go.dev/gopkg.in/launchdarkly/[email protected].

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.

5.0.0-beta.1

Please use v5.0.0-beta.2 instead. The beta.1 release was created with an incorrect Git tag, which cannot be corrected due to Go module proxy caching. The beta.2 release is identical except for the version string and the tag.

5.0.0-alpha.3

We are pushing some updates to the public repositories before the beta release is ready, in order to be able to test code that can only be built against public repos and not the development repos. This tag will be removed after the GA release.

4.17.2

[4.17.2] - 2020-05-13

Fixed:

• Updated the version of go-yaml that is optionally used by the file data source feature, to version 2.3.0, due to a vulnerability warning on version 2.2.1. Note that this is just the dependency version used when building the SDK; an application that uses the SDK may get different versions of its transitive dependencies depending on the package management system being used. The vulnerability would not affect normal usage of the SDK without the file data source, or with YAML files in the SDK's correct documented format.

4.17.1

[4.17.1] - 2020-04-16

Fixed:

• In streaming mode, a bug introduced in version 4.17.0 could cause a panic if the stream connection was broken and remained unavailable for a fairly long time (over half an hour).

4.17.0

[4.17.0] - 2020-03-30

Added:

• Config field StreamInitialReconnectDelay specifies how long the SDK should initially wait before retrying the stream connection after a failure. The default is one second; previously it was three seconds.

Changed:

• When the SDK retries the stream connection after a failure, the delay now increases using an exponential backoff (which is reset to the initial level if the stream remains active for at least a minute), and each delay also has a random jitter from 0 to -50%. Previously, every retry used a three-second delay.

4.16.2

[4.16.2] - 2020-03-13

Added:

• CI tests now verify that the SDK supports Go 1.14.

Fixed:

• In streaming mode, when using a persistent data store such as Redis, if the database was unavailable when the client initially started and made its first stream connection, a bug caused the SDK to give up on retrying and leave the client in a failed state. This has been fixed so that it will retry the stream connection once it detects that the database is available again (or, if using infinite caching mode, it will leave the same stream connection open and write the already-cached data to the database).

4.16.1

[4.16.1] - 2020-02-10

Changed:

• Diagnostic events reported by this SDK now have an SDK name of go-server-sdk instead of Go.

4.16.0

[4.16.0] - 2020-02-04

This release introduces new types for building user properties and representing arbitrary JSON values. In the next major version, these will entirely replace the current deprecated equivalents.

Added:

• NewUserBuilder, and its associated interfaces UserBuilder and UserBuilderCanMakeAttributePrivate. This is the new preferred mechanism for creating User instances when you need to set multiple properties; it reduces unsafe and inconvenient use of pointers.
• User property getter methods such as GetName().
• The SDK has a new dependency on gopkg.in/launchdarkly/go-sdk-common.v1, which provides the helper types ldvalue.Value and ldvalue.OptionalString.
• In LDClient, JSONVariation and JSONVariationDetail are the new preferred mechanism for evaluating flags whose values can be of any JSON type. The value is represented as an ldvalue.Value rather than a json.RawMessage, but can be easily converted to json.RawMessage or to other Go types.
• In LDClient, TrackData and TrackMetric are the new preferred versions of Track and TrackWithMetric; they use ldvalue.Value rather than interface{} for the data parameter.
• EvaluationReason methods GetRuleIndex(), GetRuleID(), GetPrerequisiteKey(), GetErrorKind(). These were formerly only on concrete implementation types such as EvaluationReasonRuleMatch; they are being added to the interface type because in a future version, it will be changed to a struct.

Fixed:

• By default, the SDK should log to os.Stderr with a minimum level of ldlog.Info, omitting only Debug-level messages. A bug introduced in 4.12.0 caused the default logger not to produce any output. It will now log at Info level by default again, as documented.

Deprecated:

• All exported fields of User. In a future version, these will be hidden. Use getters such as GetName() to read these fields, and NewUserBuilder to set them.
• In LDClient, JsonVariation, JsonVariationDetail, Track, and TrackWithMetric. Use JSONVariation, JSONVariationDetail, TrackData, TrackEvent, or TrackMetric instead.
• The EvaluationReason implementation types such as EvaluationReasonRuleMatch are deprecated. Instead of casting to these types, use EvaluationReason methods such as GetKind() and GetErrorKind().

4.15.0

[4.15.0] - 2020-01-23

Note: if you are using the LaunchDarkly Relay Proxy to forward events, update the Relay to version 5.10.0 or later before updating to this Go SDK version.

Added:

• The SDK now periodically sends diagnostic data to LaunchDarkly, describing the version and configuration of the SDK, the architecture and version of the runtime platform, and performance statistics. No credentials, hostnames, or other identifiable values are included. This behavior can be disabled with Config.DiagnosticOptOut or configured with Config.DiagnosticRecordingInterval.
• New Config fields WrapperName and WrapperVersion allow a library that uses the Go SDK to identify itself for usage data if desired.