split_openfeature_provider_dart_server 0.1.0
split_openfeature_provider_dart_server: ^0.1.0 copied to clipboard
Split OpenFeature provider for Dart (server-side / dynamic-context) — adapts splitio_server_side to the openfeature_dart_server_sdk FeatureProvider contract.
Split OpenFeature Provider for Dart (server-side) #
Adapts the Split Dart server-side SDK (splitio_server_side) to the
OpenFeature FeatureProvider
contract defined by openfeature_dart_server_sdk.
Overview #
This provider lets you evaluate Split feature flags through OpenFeature's standard server-side (dynamic-context) API: one provider serves every user, and the targeting key is passed on each evaluation.
The provider can be created from an SDK key, a Split factory, or a Split client.
Getting started #
Add the dependency #
Both openfeature_dart_server_sdk and splitio_server_side are peer packages
and must be declared alongside this provider. The minimum supported
openfeature_dart_server_sdk is 0.0.26 (the first version whose
ProviderLifecycleEvent carries flagsChanged); 0.1.x is supported.
dependencies:
split_openfeature_provider_dart_server: ^0.1.0
openfeature_dart_server_sdk: '>=0.0.26'
splitio_server_side: '>=1.0.0'
Register the Split provider with OpenFeature using the SDK key #
import 'package:openfeature_dart_server_sdk/open_feature_api.dart';
import 'package:split_openfeature_provider_dart_server/split_openfeature_provider_dart_server.dart';
Future<void> main() async {
final provider = OpenFeatureSplitProvider('SERVER_SIDE_SDK_KEY');
// Waits for the Split SDK to become ready; throws on ready timeout.
await OpenFeatureAPI().setProviderAndWait(provider);
final client = OpenFeatureAPI().getClient('my-service');
}
Pass config: SplitClientConfig(...) to customize the SDK (only accepted with
an SDK key). Shutting the provider down destroys the factory it created.
Register the Split provider with OpenFeature using a Split factory #
import 'package:splitio_server_side/splitio_server_side.dart'
show SplitFactory, SplitClientConfig;
final factory = SplitFactory.create(
'SERVER_SIDE_SDK_KEY',
const SplitClientConfig(),
);
await OpenFeatureAPI().setProviderAndWait(OpenFeatureSplitProvider(factory));
Shutting the provider down destroys the factory.
Register the Split provider with OpenFeature using a Split client #
final factory = SplitFactory.create(
'SERVER_SIDE_SDK_KEY',
const SplitClientConfig(),
);
await OpenFeatureAPI().setProviderAndWait(
OpenFeatureSplitProvider(factory.client()),
);
Shutting the provider down destroys only the client; call
factory.destroy() yourself.
Any other argument type throws an ArgumentError.
Evaluating flags #
Every evaluation needs an EvaluationContext with a non-empty
targetingKey — it identifies the subject of evaluation. A missing key
returns the default value with TARGETING_KEY_MISSING.
final showBanner = await client.getBooleanFlag(
'show_banner',
defaultValue: false,
context: const EvaluationContext(targetingKey: 'user-123', attributes: {}),
);
Attributes on the EvaluationContext (other than trafficType) are forwarded
to Split as evaluation attributes.
Evaluate with details #
Use the get*Details variants to retrieve the value alongside variant,
reason, error code, and flag metadata. This provider exposes the raw Split
treatment config JSON string under flagMetadata['config'].
final details = await client.getBooleanDetails(
'bool_flag',
context: const EvaluationContext(targetingKey: 'user-123', attributes: {}),
);
final config = details.flagMetadata['config']; // raw JSON string, or ''
Treatment parsing #
| OpenFeature method | Accepted treatments |
|---|---|
getBooleanFlag / Details |
'on', 'true' → true; 'off', 'false' → false |
getStringFlag / Details |
Any Split treatment string |
getIntegerFlag / Details |
Any string parseable by int.tryParse |
getDoubleFlag / Details |
Any string parseable by double.tryParse (NaN rejected) |
getObjectFlag |
Any JSON object literal (arrays, scalars, null rejected) |
Boolean matching is case-insensitive. Any treatment that fails to parse
(e.g. '32abc', '1.5' for an integer, [1,2] or null for an object)
returns the default with PARSE_ERROR. A Split 'control' treatment returns
the default with FLAG_NOT_FOUND.
Provider events #
- Split SDK ready →
PROVIDER_READY, also when it becomes ready after a timeout. Before that, evaluations return the default withPROVIDER_NOT_READY. - Split SDK ready timeout →
PROVIDER_ERROR('Split SDK ready timed out'). - Split flag and segment updates →
PROVIDER_CONFIGURATION_CHANGEDwith the changed flag names inevent.flagsChanged(empty for segment updates).
Events carry no ready/update metadata, and there is no PROVIDER_STALE
(no ready-from-cache signal). The OpenFeature SDK delivers PROVIDER_READY
twice (once from the provider and once from the SDK itself).
client.events.listen((event) {
if (event.type == OpenFeatureEventType.PROVIDER_CONFIGURATION_CHANGED) {
print('Flags changed: ${event.flagsChanged}');
}
});
Tracking #
track forwards to Split's event tracker. The event name must be non-empty
and the EvaluationContext MUST carry a targetingKey and a non-empty String
trafficType attribute. It is never defaulted, and it is ignored on
evaluation.
await client.track(
'checkout.completed',
context: const EvaluationContext(
targetingKey: 'user-123',
attributes: {'trafficType': 'account'},
),
trackingDetails: const TrackingEventDetails(
value: 19.99,
attributes: {'plan': 'pro'},
),
);
TrackingEventDetails.value is forwarded as a double; its attributes are
forwarded as Split event properties. The OpenFeature client's track()
catches and logs provider errors (e.g. a missing trafficType).
Shutting down #
shutdown is idempotent: it stops forwarding Split events, destroys the
Split factory (only the client when created from a client), and closes the
event stream. initialize after shutdown is rejected.
await OpenFeatureAPI().shutdownProvider();
Platform support #
Dart VM, the same platform as splitio_server_side.
Submitting issues #
The Split team monitors all issues submitted to this issue tracker. We encourage you to use it for bug reports, feature requests, and questions.
Contributing #
Please see
AGENTS.md for the development commands and
conventions. Run dart format --set-exit-if-changed . && dart analyze && dart test
before opening a pull request.
License #
Licensed under the Apache License, Version 2.0. See Apache License.
About Split #
Split is the leading Feature Delivery Platform for engineering teams that want to confidently deploy features as fast as they can develop them. Learn more at split.io.