From 691a2d7f99b9de9b6d49b7a0f8d2e20d22610bb5 Mon Sep 17 00:00:00 2001 From: lzrf0cuz <20177103+lzrf0cuz@users.noreply.github.com> Date: Sun, 14 Dec 2025 16:09:19 -0500 Subject: [PATCH] Complete architectural rewrite with modern SDK support, production-grade lifecycle management, and critical bug fixes. See CHANGELOG.md for a detailed list of changes, including: - Breaking changes (SDK requirements, API changes) - New features (context-aware lifecycle, event system, observability) - Bug fixes (ObjectEvaluation, dynamic configuration) - Concurrency and reliability improvements - See MIGRATION.md for upgrade instructions from v1.x. --- .gitignore | 97 +++- .golangci.yml | 139 +++++ .mockery.yaml | 14 + CHANGELOG.md | 125 +++++ CHANGES.txt | 4 - CONTRIBUTING.md | 384 +++++++++++++ CONTRIBUTORS-GUIDE.md | 28 - MIGRATION.md | 258 +++++++++ README.md | 795 +++++++++++++++++++++++--- Taskfile.yml | 366 ++++++++++++ benchmark_test.go | 166 ++++++ client.go | 26 + concurrency_test.go | 184 ++++++ config.go | 51 ++ constants.go | 68 +++ doc.go | 42 ++ docs/images/of_banner.png | Bin 0 -> 214563 bytes evaluation.go | 505 +++++++++++++++++ evaluation_options_test.go | 125 +++++ evaluation_test.go | 959 ++++++++++++++++++++++++++++++++ events.go | 220 ++++++++ examples/cloud/README.md | 61 ++ examples/cloud/main.go | 214 +++++++ examples/localhost/README.md | 79 +++ examples/localhost/main.go | 203 +++++++ examples/localhost/split.yaml | 46 ++ go.mod | 37 +- go.sum | 158 ++---- helpers.go | 428 ++++++++++++++ lifecycle.go | 490 ++++++++++++++++ lifecycle_edge_cases_test.go | 915 ++++++++++++++++++++++++++++++ lifecycle_test.go | 249 +++++++++ logging.go | 105 ++++ logging_test.go | 363 ++++++++++++ mock_client_test.go | 324 +++++++++++ mock_evaluation_test.go | 574 +++++++++++++++++++ options.go | 111 ++++ options_test.go | 88 +++ provider.go | 416 +++++++------- provider_test.go | 762 ++++++++++++------------- split.yaml | 14 - test/advanced/README.md | 65 +++ test/advanced/main.go | 354 ++++++++++++ test/cloud_flags.yaml | 87 +++ test/integration/README.md | 75 +++ test/integration/evaluations.go | 611 ++++++++++++++++++++ test/integration/lifecycle.go | 538 ++++++++++++++++++ test/integration/main.go | 428 ++++++++++++++ test/integration/results.go | 78 +++ test/integration/sdk.go | 353 ++++++++++++ test/integration/split.yaml | 107 ++++ testdata/split.yaml | 37 ++ track_test.go | 126 +++++ 53 files changed, 12204 insertions(+), 848 deletions(-) create mode 100644 .golangci.yml create mode 100644 .mockery.yaml create mode 100644 CHANGELOG.md delete mode 100644 CHANGES.txt create mode 100644 CONTRIBUTING.md delete mode 100644 CONTRIBUTORS-GUIDE.md create mode 100644 MIGRATION.md create mode 100644 Taskfile.yml create mode 100644 benchmark_test.go create mode 100644 client.go create mode 100644 concurrency_test.go create mode 100644 config.go create mode 100644 constants.go create mode 100644 doc.go create mode 100644 docs/images/of_banner.png create mode 100644 evaluation.go create mode 100644 evaluation_options_test.go create mode 100644 evaluation_test.go create mode 100644 events.go create mode 100644 examples/cloud/README.md create mode 100644 examples/cloud/main.go create mode 100644 examples/localhost/README.md create mode 100644 examples/localhost/main.go create mode 100644 examples/localhost/split.yaml create mode 100644 helpers.go create mode 100644 lifecycle.go create mode 100644 lifecycle_edge_cases_test.go create mode 100644 lifecycle_test.go create mode 100644 logging.go create mode 100644 logging_test.go create mode 100644 mock_client_test.go create mode 100644 mock_evaluation_test.go create mode 100644 options.go create mode 100644 options_test.go delete mode 100644 split.yaml create mode 100644 test/advanced/README.md create mode 100644 test/advanced/main.go create mode 100644 test/cloud_flags.yaml create mode 100644 test/integration/README.md create mode 100644 test/integration/evaluations.go create mode 100644 test/integration/lifecycle.go create mode 100644 test/integration/main.go create mode 100644 test/integration/results.go create mode 100644 test/integration/sdk.go create mode 100644 test/integration/split.yaml create mode 100644 testdata/split.yaml create mode 100644 track_test.go diff --git a/.gitignore b/.gitignore index b986336..35087fe 100644 --- a/.gitignore +++ b/.gitignore @@ -1,17 +1,102 @@ -# Binaries for programs and plugins +# ============================================================================= +# Go +# ============================================================================= + +# Binaries *.exe *.exe~ *.dll *.so *.dylib -# Test binary, built with `go test -c` +# Test binaries *.test -# Output of the go coverage tool, specifically when used with LiteIDE +# Coverage output *.out +coverage.out + +# Go workspace +go.work +go.work.sum + +# ============================================================================= +# Project +# ============================================================================= + +# Environment files (may contain secrets) +*.env +.env.local + +# Task runner cache +.task/ + +# Split SDK local files +.split +.splits + +# ============================================================================= +# IDE - JetBrains (GoLand, IntelliJ) +# ============================================================================= + +.idea/* +!.idea/codeStyles/ +!.idea/runConfigurations/ + +*.iml +*.ipr +*.iws + +# ============================================================================= +# IDE - VS Code +# ============================================================================= + +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +!.vscode/*.code-snippets + +.history/ +*.vsix + +# ============================================================================= +# OS - macOS +# ============================================================================= + +.DS_Store +.AppleDouble +.LSOverride +._* +.Spotlight-V100 +.Trashes + +# ============================================================================= +# OS - Windows +# ============================================================================= + +Thumbs.db +ehthumbs.db +Desktop.ini +$RECYCLE.BIN/ +*.lnk + +# ============================================================================= +# OS - Linux +# ============================================================================= + +*~ +.directory +.Trash-* +.nfs* -# Dependency directories (remove the comment below to include it) -# vendor/ +# ============================================================================= +# Git +# ============================================================================= -.idea/ \ No newline at end of file +*.orig +*.BACKUP.* +*.BASE.* +*.LOCAL.* +*.REMOTE.* diff --git a/.golangci.yml b/.golangci.yml new file mode 100644 index 0000000..71ada67 --- /dev/null +++ b/.golangci.yml @@ -0,0 +1,139 @@ +# golangci-lint configuration for Split OpenFeature Provider +# Gold Standard Linting Configuration + +version: "2" + +run: + timeout: 5m + tests: true + modules-download-mode: readonly + +linters: + enable: + # Enabled by default + - errcheck # Check for unchecked errors + - govet # Go vet + - ineffassign # Detect ineffectual assignments + - staticcheck # Static analysis + - unused # Check for unused code + + # Additional recommended linters + - misspell # Check for misspelled words + - unconvert # Remove unnecessary type conversions + - unparam # Report unused function parameters + - prealloc # Find slice declarations that could be preallocated + - goconst # Find repeated strings that could be constants + - gocyclo # Cyclomatic complexity + - gocognit # Cognitive complexity + - dupl # Code clone detection + - gocritic # Comprehensive checks + - revive # Fast, extensible linter + - gosec # Security checks + - bodyclose # Check HTTP response bodies are closed + - noctx # Detect http.Request without context.Context + - rowserrcheck # Check sql.Rows.Err is checked + - sqlclosecheck # Check sql.Rows and sql.Stmt are closed + - errorlint # Error wrapping checks + - exhaustive # Check exhaustiveness of enum switch statements + + exclusions: + paths: + - examples + - test + - '.*\.pb\.go$' + + rules: + # Exclude all linters from test files - focus on production code quality + - path: '(.+)_test\.go' + linters: + - errcheck + - gocyclo + - gocognit + - dupl + - gocritic + - gosec + - goconst + - govet + - revive + - staticcheck + - misspell + - unconvert + - unparam + - prealloc + + settings: + errcheck: + check-type-assertions: true + check-blank: true + + govet: + enable-all: true + disable: + - shadow # Too many false positives + + gocyclo: + min-complexity: 15 + + gocognit: + min-complexity: 30 + + dupl: + threshold: 100 + + goconst: + min-len: 3 + min-occurrences: 3 + + misspell: + locale: US + + staticcheck: + checks: [ "all" ] + + revive: + confidence: 0.8 + rules: + - name: blank-imports + - name: context-as-argument + - name: context-keys-type + - name: dot-imports + - name: error-return + - name: error-strings + - name: error-naming + - name: exported + - name: if-return + - name: increment-decrement + - name: var-declaration + - name: package-comments + - name: range + - name: receiver-naming + - name: time-naming + - name: unexported-return + - name: indent-error-flow + - name: errorf + - name: empty-block + - name: superfluous-else + - name: unused-parameter + - name: unreachable-code + - name: redefines-builtin-id + + gosec: + severity: medium + confidence: medium + + gocritic: + enabled-tags: + - diagnostic + - performance + - style + disabled-checks: + - commentedOutCode + - whyNoLint + + exhaustive: + default-signifies-exhaustive: true + + prealloc: + simple: true + range-loops: true + for-loops: false diff --git a/.mockery.yaml b/.mockery.yaml new file mode 100644 index 0000000..8a18cc0 --- /dev/null +++ b/.mockery.yaml @@ -0,0 +1,14 @@ +# Mockery v3.6.4 configuration +# See: https://github.com/vektra/mockery/blob/v3/docs/configuration.md +all: false +template: testify +formatter: goimports +packages: + github.com/splitio/split-openfeature-provider-go/v2: + interfaces: + Client: + config: + dir: "{{.InterfaceDir}}" + filename: "mock_client_test.go" + pkgname: "split" + structname: "MockClient" diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..ae6d59e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,125 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [2.0.0] - 2025-11-24 + +**Complete architectural rewrite** with modern SDK support, production-grade lifecycle management, and critical bug +fixes. + +See [MIGRATION.md](MIGRATION.md) for upgrade instructions. + +### Breaking Changes + +#### SDK Requirements + +- **Split Go SDK upgraded to v6** (import: `github.com/splitio/go-client/v6`) +- **OpenFeature Go SDK upgraded to v1** (import: `github.com/open-feature/go-sdk/openfeature`) + +#### API Changes + +- **All evaluation methods now require `context.Context` as first parameter** +- **`Client()` renamed to `Factory()`** for Split SDK factory access +- **`NewWithClient()` constructor removed** - use `New()` instead + +#### Behavioral Changes + +- **`ObjectEvaluation()` return structure changed**: + - v1: Returns treatment string only + - v2: Returns `FlagSetResult` (typed struct with `Treatment` and `Config` fields) + +### New Features + +#### Context-Aware Lifecycle + +- `InitWithContext(ctx)` - Context-aware initialization with timeout and cancellation +- `ShutdownWithContext(ctx)` - Graceful shutdown with timeout and proper cleanup +- Idempotent initialization with singleflight (prevents concurrent init races) +- Provider cannot be reused after shutdown (must create new instance) + +#### Event System + +- OpenFeature event support: + - `PROVIDER_READY` - Provider initialized + - `PROVIDER_ERROR` - Initialization or runtime errors + - `PROVIDER_CONFIGURATION_CHANGED` - Flag definitions updated (detected via 30s polling) +- Background monitoring (30s interval) for configuration change detection + +#### Event Tracking + +- `Track()` method implementing OpenFeature Tracker interface +- Associates feature flag evaluations with user actions for A/B testing and experimentation +- Supports custom traffic types via `trafficType` attribute in evaluation context +- Supports event properties via `TrackingEventDetails.Add()` +- Events viewable in Split Data Hub + +#### Per-Request Evaluation Options + +- `WithEvaluationMode(ctx, mode)` - Control per-request object evaluation behavior via `context.Context` + - `EvaluationModeIndividual` - Evaluate a single flag (useful in cloud mode to bypass flag set evaluation) + - `EvaluationModeSet` - Evaluate a flag set (explicit, same as cloud default; ignored in localhost mode) + - `EvaluationModeDefault` - Use provider's default behavior (flag set in cloud, individual in localhost) +- `WithImpressionDisabled(ctx)` - Forward-looking API for per-evaluation impression control (logged, not yet enforced) +- `WithEvalOptions(ctx, opts)` - Set multiple evaluation options at once + +#### Per-Request Track Options + +- `WithoutMetricValue(ctx)` - Send nil value to Split for count-only events, preventing pollution of sum/average metrics +- `WithTrackOptions(ctx, opts)` - Set multiple tracking options at once +- `GetTrackOptions(ctx)` - Extract tracking options from context + +#### Client Interface + +- Extracted `Client` interface for dependency injection and mock generation +- Enables mockery-based mock generation for unit testing without Split SDK + +#### Observability + +- Structured logging with `log/slog` throughout provider and Split SDK +- `Metrics()` method for health status and diagnostics +- Unified logging via `WithLogger()` option + +### Bug Fixes + +#### Critical Fixes + +- **`ObjectEvaluation()` structure**: Now returns `FlagSetResult` with `Treatment` and `Config` fields (was: treatment + string only) +- **Dynamic Configuration**: All config types (objects, primitives, arrays) consistently accessible via + `FlagMetadata["value"]` +- **Dynamic Configuration JSON parsing**: Supports objects, arrays, and primitives (was: limited support) +- **Evaluation context attributes**: Now passed to Split SDK for targeting rules (was: ignored) +- **Shutdown resource cleanup**: Properly cleans up goroutines, channels, and SDK clients (was: resource leaks) + +#### Error Handling + +- **Shutdown timeout errors**: `ShutdownWithContext()` returns `ctx.Err()` when cleanup times out (was: no error + indication) +- **JSON parse warnings**: Malformed Dynamic Configuration logged instead of silent failures +- **Targeting key validation**: Non-string keys rejected with clear errors (was: silent failures) + +#### Concurrency & Reliability + +- **Atomic initialization**: Factory, client, and manager ready together (was: race conditions) +- **Thread-safe health checks**: Eliminated race conditions in `Status()` and `Metrics()` +- **Event channel lifecycle**: Properly closed during shutdown (was: potential goroutine leaks) +- **Panic recovery**: Monitoring goroutine recovers from panics and terminates gracefully + +## [1.0.1] - 2022-10-14 + +- Updated to OpenFeature spec v0.5.0 and OpenFeature Go SDK v0.6.0 + +## [1.0.0] - 2022-10-03 + +- Initial release +- OpenFeature spec v0.5.0 compliance +- OpenFeature Go SDK v0.5.0 support + +[2.0.0]: https://github.com/splitio/split-openfeature-provider-go/compare/v1.0.1...v2.0.0 + +[1.0.1]: https://github.com/splitio/split-openfeature-provider-go/compare/v1.0.0...v1.0.1 + +[1.0.0]: https://github.com/splitio/split-openfeature-provider-go/releases/tag/v1.0.0 diff --git a/CHANGES.txt b/CHANGES.txt deleted file mode 100644 index d70bf22..0000000 --- a/CHANGES.txt +++ /dev/null @@ -1,4 +0,0 @@ -1.0.0 -- 10/3/2022. Up to date with spec v0.5.0 and go sdk v0.5.0 -1.0.1 -- 10/14/2022. Up to date with spec v0.5.0 and go sdk v0.6.0 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..12aeff0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,384 @@ +# Contributing to Split OpenFeature Go Provider + +We welcome contributions! This guide covers how to build, test, and submit changes. + +**Quick Links:** + +- [README.md](README.md) - Main documentation +- [MIGRATION.md](MIGRATION.md) - v1 → v2 migration guide +- [CHANGELOG.md](CHANGELOG.md) - Version history + +--- + +## Prerequisites + +- **Go 1.25.4+** +- **Task** - [taskfile.dev](https://taskfile.dev) +- **golangci-lint** - For linting + +### Install Task + +```bash +# macOS +brew install go-task/tap/go-task + +# Linux +sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin + +# Via Go +go install github.com/go-task/task/v3/cmd/task@latest +``` + +### Install Development Tools + +```bash +task install-tools # Install golangci-lint and other tools +task check-tools # Verify installation +``` + +--- + +## Development Workflow + +### 1. Fork and Clone + +```bash +git clone https://github.com/YOUR_USERNAME/split-openfeature-provider-go.git +cd split-openfeature-provider-go +git remote add upstream https://github.com/splitio/split-openfeature-provider-go.git +``` + +### 2. Create Feature Branch + +```bash +git fetch upstream +git checkout -b feat/your-feature-name upstream/main +``` + +### 3. Make Changes + +**Run tests first:** + +```bash +task test # Run all tests with race detector +``` + +**Make your changes:** + +- Add tests for new functionality (use testify/assert) +- Follow Go idioms and best practices +- Add godoc comments for exported symbols +- Keep functions focused and small + +**Validate:** + +```bash +task # Run lint + test + coverage +task pre-commit # Quick pre-commit checks +``` + +### 4. Write Tests + +**Requirements:** + +- Use `testify/assert` or `testify/require` for assertions +- Maintain >70% coverage (`task coverage-check`) +- Tests must pass race detector +- Test both success and error cases + +**Example:** + +```go +func TestFeatureName(t *testing.T) { + provider, err := setupTestProvider(t) + require.NoError(t, err, "Setup failed") + + tests := []struct { + name string + input string + expected string + wantErr bool + }{ + {"valid input", "test", "expected", false}, + {"invalid input", "", "", true}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result, err := provider.YourMethod(tt.input) + + if tt.wantErr { + assert.Error(t, err) + } else { + assert.NoError(t, err) + assert.Equal(t, tt.expected, result) + } + }) + } +} +``` + +### 5. Commit and Push + +**Use Conventional Commits:** + +```bash +git commit -m "feat: add new feature" +git commit -m "fix: resolve bug with shutdown" +git commit -m "docs: update README examples" +``` + +**Types:** `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore` + +```bash +git push origin feat/your-feature-name +``` + +### 6. Create Pull Request + +**PR Checklist:** + +- [ ] All tests pass (`task test`) +- [ ] Linter passes (`task lint`) +- [ ] Coverage maintained at >70% (`task coverage-check`) +- [ ] Documentation updated +- [ ] Godoc comments added +- [ ] No goroutine leaks +- [ ] Concurrency safety verified + +--- + +## Testing + +### Unit Tests + +```bash +task test # All tests with race detector +task test-short # Quick test run +task coverage # View coverage report +task coverage-check # Verify 70% threshold +``` + +### Integration Tests + +```bash +task test-integration # Uses SPLIT_API_KEY if set, otherwise localhost mode +task test-cloud # Cloud-only features (requires SPLIT_API_KEY) +``` + +**Integration Test (`test/integration/`)** - Automated test suite: + +- Localhost mode: 85 tests (no API key needed) +- Cloud mode: 94 tests (requires SPLIT_API_KEY) +- All evaluation types (boolean, string, int, float, object) +- Lifecycle management and concurrent evaluations +- Event handling and dynamic configurations + +**Cloud Test (`test/advanced/`)** - Cloud-only features: + +- Event tracking (view in Split Data Hub) +- Configuration change detection +- Interactive testing for cloud-specific functionality + +**Cloud Mode Testing Setup:** + +To run integration tests in cloud mode, create the required flags in your Split.io account. +See `test/cloud_flags.yaml` for the flag definitions: + +1. Create 11 flags as documented in `test/cloud_flags.yaml` +2. Create a flag set named `split_provider_test` +3. Add `ui_theme` and `api_version` flags to the flag set +4. Run tests: + +```bash +SPLIT_API_KEY="your-key" task test-integration +``` + +**When Are These Tests Executed?** + +Neither test suite runs as part of CI (`task ci`). Run manually: + +```bash +# Integration test - localhost mode (no API key) +task test-integration + +# Integration test - cloud mode (requires API key and flags) +SPLIT_API_KEY="your-key" task test-integration + +# Cloud test - cloud mode (requires API key) +SPLIT_API_KEY="your-key" task test-cloud +``` + +**Recommendation:** Run `task test-integration` before submitting PRs that affect: + +- Provider initialization/shutdown +- Flag evaluation logic +- Event handling +- Dynamic configuration parsing + +--- + +## Code Quality + +### Required Standards + +- All exported symbols must have godoc comments +- golangci-lint must pass +- Coverage >70% +- No race conditions +- No goroutine leaks +- Thread-safety verified for shared state + +### Common Commands + +```bash +# Workflows +task # Show available tasks +task check # Run all quality checks +task pre-commit # Quick pre-commit +task ci # Full CI suite + +# Testing +task test # Unit tests with race detector +task test-integration # Integration tests (localhost or cloud) +task test-cloud # Cloud-only tests (requires API key) +task coverage # Coverage report + +# Code Quality +task lint # Run linter +task lint-fix # Auto-fix issues +task fmt # Format code +task vet # Run go vet + +# Examples +task example-cloud # Cloud mode (requires SPLIT_API_KEY) +task example-localhost # Localhost mode (no API key) + +# Tools +task install-tools # Install dev tools +task clean # Clean artifacts +``` + +--- + +## Project Structure + +``` +split-openfeature-provider-go/ +├── provider.go # Core provider +├── lifecycle.go # Init/Shutdown (context-aware) +├── events.go # Event system +├── evaluation.go # Flag evaluations +├── helpers.go # Helpers and Factory() +├── logging.go # Slog adapter +├── constants.go # Constants +├── provider_test.go # Unit tests +├── lifecycle_edge_cases_test.go # Concurrency tests +├── examples/ +│ ├── cloud/ # Cloud mode example +│ └── localhost/ # Localhost mode example +└── test/ + ├── cloud_flags.yaml # Flag definitions for cloud testing + ├── integration/ # Integration tests (localhost + cloud) + └── advanced/ # Advanced tests (cloud-only features) +``` + +--- + +## v2 Status: Production Ready ✅ + +- ✅ Context-aware lifecycle with timeouts +- ✅ Full OpenFeature event compliance +- ✅ Optimal test coverage with race detection +- ✅ Structured logging with slog +- ✅ Thread-safe concurrent operations + +--- + +## Known Limitations & Future Enhancements + +### PROVIDER_STALE Event Not Emitted + +**Status:** Known limitation (Split SDK dependency) + +The provider cannot emit `PROVIDER_STALE` events when network connectivity is lost. This is due to a limitation in the +Split Go SDK: + +- `factory.IsReady()` only indicates **initial** readiness after `BlockUntilReady()` completes +- The method does **not** change when the SDK loses network connectivity during operation +- Internally, the SDK handles connectivity issues (switching between streaming and polling modes) but does not expose + this state through its public API + +**Impact:** + +- When network connectivity is lost, the SDK continues serving cached data silently +- Applications cannot detect when they are receiving potentially stale feature flag values +- The `PROVIDER_CONFIGURATION_CHANGED` event still works correctly when flags are updated + +**Potential Future Enhancement:** +If the Split SDK exposes streaming/connectivity status in a future version, this provider could be updated to: + +1. Monitor the streaming status channel for `StatusUp`/`StatusDown` events +2. Emit `PROVIDER_STALE` when streaming disconnects and polling begins +3. Emit `PROVIDER_READY` when streaming reconnects + +**Workaround for Applications:** +Applications requiring staleness awareness should implement application-level health checks, such as: + +- Periodic test evaluations with known flags +- Monitoring SDK debug logs for connectivity errors +- External health check endpoints to Split.io APIs + +**References:** + +- Split SDK sync manager: `go-split-commons/synchronizer/manager.go` +- Push status constants: `StatusUp`, `StatusDown`, `StatusRetryableError`, `StatusNonRetryableError` +- SSE keepAlive timeout: 70 seconds (hardcoded in SDK) + +### PROVIDER_CONFIGURATION_CHANGED Detected via Polling + +**Status:** Known limitation (Split SDK dependency) + +The `PROVIDER_CONFIGURATION_CHANGED` event is detected by polling, not via real-time SSE streaming. The polling interval +is configurable via `WithMonitoringInterval` (default: 30 seconds, minimum: 5 seconds). + +**Why Polling?** + +- The Split SDK receives configuration changes instantly via SSE streaming +- However, the SDK does **not** expose a callback or event for configuration changes +- The only way to detect changes is by polling `manager.Splits()` and comparing `ChangeNumber` values + +**Impact:** + +- Flag evaluations reflect changes immediately (SDK updates its cache via SSE) +- `PROVIDER_CONFIGURATION_CHANGED` events have latency up to the configured monitoring interval +- Applications relying on this event for cache invalidation may see delayed notifications + +**Potential Future Enhancement:** +If the Split SDK exposes a configuration change callback in a future version, this provider could be updated to: + +1. Register a callback for real-time change notifications +2. Emit `PROVIDER_CONFIGURATION_CHANGED` immediately when changes arrive via SSE +3. Remove the polling-based detection + +--- + +## Resources + +**Documentation:** + +- [OpenFeature Specification](https://openfeature.dev/specification/sections/providers) +- [OpenFeature Go SDK](https://openfeature.dev/docs/reference/sdks/server/go/) +- [Split Go SDK](https://github.com/splitio/go-client) +- [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments) + +**Help:** + +- [GitHub Issues](https://github.com/splitio/split-openfeature-provider-go/issues) - Bug reports and feature requests +- [Pull Requests](https://github.com/splitio/split-openfeature-provider-go/pulls) - Contributions + +--- + +## License + +By contributing, you agree your contributions will be licensed under Apache License 2.0. diff --git a/CONTRIBUTORS-GUIDE.md b/CONTRIBUTORS-GUIDE.md deleted file mode 100644 index b5653a6..0000000 --- a/CONTRIBUTORS-GUIDE.md +++ /dev/null @@ -1,28 +0,0 @@ -# Contributing to the Split OpenFeature Provider - -The Split Provider is an open source project and we welcome feedback and contribution. The information below describes how to build the project with your changes, run the tests, and send the Pull Request(PR). - -## Development - -### Development process - -1. Fork the repository and create a topic branch from `development` branch. Please use a descriptive name for your branch. -2. While developing, use descriptive messages in your commits. Avoid short or meaningless sentences like "fix bug". -3. Make sure to add tests for both positive and negative cases. -4. Run the build script and make sure it runs with no errors. -5. Run all tests and make sure there are no failures. -6. `git push` your changes to GitHub within your topic branch. -7. Open a Pull Request(PR) from your forked repo and into the `development` branch of the original repository. -8. When creating your PR, please fill out all the fields of the PR template, as applicable, for the project. -9. Check for conflicts once the pull request is created to make sure your PR can be merged cleanly into `development`. -10. Keep an eye out for any feedback or comments from the Split team. - -### Building the Split Provider -- `go build` - -### Running tests -- `go test` - -# Contact - -If you have any other questions or need to contact us directly in a private manner send us a note at sdks@split.io diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..a2ea07f --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,258 @@ +# Migration Guide: v1 to v2 + +## Overview + +Version 2.0.0 includes critical bug fixes and SDK upgrades. + +### Bug Fixes + +- `ObjectEvaluation()` returns structured map with treatment and config fields +- Dynamic Configuration supports any JSON type (objects, arrays, primitives) +- Evaluation context attributes passed to Split SDK for targeting rules +- `Shutdown()` properly cleans up all resources +- Non-string targeting keys validated and rejected + +### SDK Updates + +- Split Go SDK updated to v6 +- OpenFeature Go SDK updated to v1 +- Go minimum version: 1.25 + +## Breaking Changes + +### Import Paths + +```go +// v1 +import ( + "github.com/splitio/go-client/splitio/client" + "github.com/open-feature/go-sdk/pkg/openfeature" +) + +// v2 +import ( + "github.com/splitio/go-client/v6/splitio/client" + "github.com/open-feature/go-sdk/openfeature" +) +``` + +### Provider Initialization + +Use `SetProviderWithContextAndWait()` for synchronous initialization with timeout: + +```go +// v1 +openfeature.SetProvider(provider) + +// v2 - Recommended with context and timeout +ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) +defer cancel() + +err := openfeature.SetProviderWithContextAndWait(ctx, provider) +if err != nil { + log.Fatal(err) +} + +// v2 - Alternative: No timeout (uses default from BlockUntilReady config) +err = openfeature.SetProviderAndWait(provider) +if err != nil { + log.Fatal(err) +} +``` + +### Context Required + +```go +// v1 +result, _ := client.BooleanValue(nil, "flag-key", false, evalCtx) + +// v2 +ctx := context.Background() +result, _ := client.BooleanValue(ctx, "flag-key", false, evalCtx) +``` + +## Migration Steps + +### 1. Update Dependencies + +```bash +go get github.com/splitio/split-openfeature-provider-go/v2@latest +go get github.com/splitio/go-client/v6@latest +go get github.com/open-feature/go-sdk@latest +go mod tidy +``` + +### 2. Update Imports + +```go +import ( + "context" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/split-openfeature-provider-go/v2" +) +``` + +### 3. Update Initialization + +```go +provider, err := split.New(apiKey) +if err != nil { + log.Fatal(err) +} + +// Defer shutdown with context +defer func() { + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + if err := openfeature.ShutdownWithContext(ctx); err != nil { + log.Printf("Shutdown error: %v", err) + } +}() + +// Initialize with context and timeout +ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) +defer cancel() + +err = openfeature.SetProviderWithContextAndWait(ctx, provider) +if err != nil { + log.Fatal(err) +} + +client := openfeature.NewClient("my-app") +``` + +### 4. Add Context to Evaluations + +```go +ctx := context.Background() +evalCtx := openfeature.NewEvaluationContext("user-123", map[string]any{ + "email": "user@example.com", +}) +result, _ := client.BooleanValue(ctx, "my-feature", false, evalCtx) +``` + +## Behavioral Changes + +### Dynamic Configurations + +v1 returned treatment name. v2 returns structured map with treatment and config: + +```go +result, _ := client.ObjectValue(ctx, "my-flag", split.FlagSetResult{}, evalCtx) +// v1: "on" (treatment only) +// v2: {"my-flag": {"treatment": "on", "config": {"feature": "enabled", "limit": 100}}} + +// Dynamic Configuration is accessible via FlagMetadata["value"] +details, _ := client.StringValueDetails(ctx, "my-flag", "default", evalCtx) +if configValue, ok := details.FlagMetadata["value"]; ok { + // All config types wrapped in "value" key for consistent access + // Object: configValue.(map[string]any) + // Primitive: configValue.(float64), configValue.(string), etc. + // Array: configValue.([]any) +} +``` + +### Targeting Rules + +v1 ignored evaluation context attributes. v2 passes them correctly: + +```go +evalCtx := openfeature.NewEvaluationContext("user-123", map[string]any{ + "plan": "premium", +}) +result, _ := client.BooleanValue(ctx, "premium-feature", false, evalCtx) +// v1: attributes ignored +// v2: targeting rules work +``` + +### Logging + +v1 used plain text logs. v2 uses structured JSON logs with `slog`. + +## New Features + +### Custom Logger + +```go +logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{ + Level: slog.LevelInfo, +})) +slog.SetDefault(logger) +``` + +### Health Check + +```go +metrics := provider.Metrics() +``` + +### Factory Access + +```go +factory := provider.Factory() +manager := factory.Manager() +``` + +## Compatibility + +| Component | v1.x | v2.x | +|-----------------|-------|-------| +| Go Version | 1.19+ | 1.25+ | +| Split SDK | v5/v6 | v6 | +| OpenFeature SDK | v0 | v1 | + +## Complete Example + +### v1 + +```go +import ( + "github.com/open-feature/go-sdk/pkg/openfeature" + "github.com/splitio/split-openfeature-provider-go" +) + +provider, _ := split.NewProviderSimple("YOUR_API_KEY") +openfeature.SetProvider(provider) +client := openfeature.NewClient("my-app") + +evalCtx := openfeature.NewEvaluationContext("user-123", nil) +result, _ := client.BooleanValue(nil, "my-feature", false, evalCtx) +``` + +### v2 + +```go +import ( + "context" + "log" + "time" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/split-openfeature-provider-go/v2" +) + +provider, err := split.New("YOUR_API_KEY") +if err != nil { + log.Fatal(err) +} + +defer func() { + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + openfeature.ShutdownWithContext(ctx) +}() + +ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) +defer cancel() + +err = openfeature.SetProviderWithContextAndWait(ctx, provider) +if err != nil { + log.Fatal(err) +} + +client := openfeature.NewClient("my-app") + +evalCtx := openfeature.NewEvaluationContext("user-123", nil) +result, _ := client.BooleanValue(context.Background(), "my-feature", false, evalCtx) +``` diff --git a/README.md b/README.md index 25b6945..a164961 100644 --- a/README.md +++ b/README.md @@ -1,112 +1,759 @@ -# Split OpenFeature Provider for Go -[![Twitter Follow](https://img.shields.io/twitter/follow/splitsoftware.svg?style=social&label=Follow&maxAge=1529000)](https://twitter.com/intent/follow?screen_name=splitsoftware) +
+ +OpenFeature Banner + +# Split OpenFeature Go Provider + +[![Report Card](https://goreportcard.com/badge/github.com/splitio/split-openfeature-provider-go?style=for-the-badge&logo=go)](https://goreportcard.com/report/github.com/splitio/split-openfeature-provider-go) +[![Coverage](https://img.shields.io/badge/coverage-85.0%25-brightgreen?style=for-the-badge&logo=go)](https://github.com/splitio/split-openfeature-provider-go) +[![Reference](https://img.shields.io/badge/reference-docs-007d9c?style=for-the-badge&logo=go&logoColor=white)](https://pkg.go.dev/github.com/splitio/split-openfeature-provider-go/v2) + +**OpenFeature Go Provider for Split.io** + +[Installation](#installation) • [Usage](#usage) • [Examples](#examples) • [API](#api) • [Contributing](#contributing) + +
+ +--- ## Overview -This Provider is designed to allow the use of OpenFeature with Split, the platform for controlled rollouts, serving features to your users via the Split feature flag to manage your complete customer experience. -## Compatibility -This SDK is compatible with Go 1.19 and higher. +OpenFeature provider for Split.io enabling feature flag evaluation through the OpenFeature SDK with support for +attribute-based targeting and flag metadata (JSON configurations attached to treatments). + +## Features -## Getting started -Below is a simple example that describes the instantiation of the Split Provider. Please see the [OpenFeature Documentation](https://docs.openfeature.dev/docs/reference/concepts/evaluation-api) for details on how to use the OpenFeature SDK. +- All OpenFeature flag types (boolean, string, number, object) +- Event tracking for experimentation and analytics +- Attribute-based targeting and flag metadata +- Configuration change detection via background monitoring +- Thread-safe concurrent evaluations +- Structured logging via `slog` + +## Installation + +```bash +go get github.com/splitio/split-openfeature-provider-go/v2 +go get github.com/open-feature/go-sdk +go get github.com/splitio/go-client/v6 +``` + +## Usage + +### Basic Setup ```go import ( - "github.com/open-feature/go-sdk/pkg/openfeature" - splitProvider "github.com/splitio/split-openfeature-provider-go" + "context" + "time" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/split-openfeature-provider-go/v2" ) -provider, err := splitProvider.NewProviderSimple("YOUR_SDK_TYPE_API_KEY") +provider, err := split.New("YOUR_API_KEY") if err != nil { - // Provider creation error + log.Fatal(err) } -openfeature.SetProvider(provider) +defer func() { + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + if err := openfeature.ShutdownWithContext(ctx); err != nil { + log.Printf("Shutdown error: %v", err) + } +}() + +ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) +defer cancel() + +if err := openfeature.SetProviderWithContextAndWait(ctx, provider); err != nil { + log.Fatal(err) +} + +client := openfeature.NewClient("my-app") ``` -If you are more familiar with Split or want access to other initialization options, you can provide a `SplitClient` to the constructor. See the [Split Go SDK Documentation](https://help.split.io/hc/en-us/articles/360020093652-Go-SDK#initialization) for more information. +### Advanced Setup + ```go -import ( - "github.com/open-feature/go-sdk/pkg/openfeature" - "github.com/splitio/go-client/v6/splitio/client" - "github.com/splitio/go-client/v6/splitio/conf" - splitProvider "github.com/splitio/split-openfeature-provider-go" -) +import "github.com/splitio/go-client/v6/splitio/conf" cfg := conf.Default() -factory, err := client.NewSplitFactory("YOUR_SDK_TYPE_API_KEY", cfg) -if err != nil { - // SDK initialization error +cfg.BlockUntilReady = 15 // Default is 10 seconds + +provider, err := split.New("YOUR_API_KEY", split.WithSplitConfig(cfg)) +``` + +See [examples](./examples/) for complete configuration patterns including logging setup. + +### Server-Side Evaluation Pattern + +In server-side SDKs, create client once at startup, then evaluate per-request with transaction-specific context: + +```go +// Application startup - create client once +client := openfeature.NewClient("my-app") + +// Per-request handler +func handleRequest(w http.ResponseWriter, r *http.Request) { + // Create evaluation context with targeting key and attributes + evalCtx := openfeature.NewEvaluationContext("user-123", map[string]any{ + "email": "user@example.com", + "plan": "premium", + }) + + // Option 1: Pass evaluation context directly to each call + enabled, _ := client.BooleanValue(r.Context(), "new-feature", false, evalCtx) + + // Option 2: Use transaction context propagation (set once, use throughout request) + ctx := openfeature.WithTransactionContext(r.Context(), evalCtx) + enabled, _ = client.BooleanValue(ctx, "new-feature", false, openfeature.EvaluationContext{}) + theme, _ := client.StringValue(ctx, "ui-theme", "light", openfeature.EvaluationContext{}) } +``` -splitClient := factory.Client() +**Required:** Targeting key in evaluation context. -err = splitClient.BlockUntilReady(10) -if err != nil { - // SDK timeout error +**Transaction context:** Use `openfeature.WithTransactionContext()` to embed evaluation context in `context.Context` +once, then reuse across multiple evaluations. + +### Domain-Specific Providers + +Use named providers for multi-tenant or service-isolated configurations: + +```go +defer func() { + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + openfeature.ShutdownWithContext(ctx) +}() + +ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) +defer cancel() + +tenant1Provider, _ := split.New("TENANT_1_API_KEY") +openfeature.SetNamedProviderWithContextAndWait(ctx, "tenant-1", tenant1Provider) + +tenant2Provider, _ := split.New("TENANT_2_API_KEY") +openfeature.SetNamedProviderWithContextAndWait(ctx, "tenant-2", tenant2Provider) + +// Create clients for each named provider domain +client1 := openfeature.NewClient("tenant-1") +client2 := openfeature.NewClient("tenant-2") +``` + +### Lifecycle Management + +#### Context-Aware Initialization + +The provider supports context-aware initialization with timeout and cancellation: + +```go +// Initialization with context (recommended) +ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) +defer cancel() + +if err := openfeature.SetProviderWithContextAndWait(ctx, provider); err != nil { + log.Fatal(err) } +``` -provider, err := splitProvider.NewProvider(*splitClient) -if err != nil { - // Provider creation error +**Key Behaviors:** + +- Respects context deadline (returns error if timeout exceeded) +- Cancellable via context cancellation +- Idempotent - safe to call multiple times (fast path if already initialized) +- Thread-safe - concurrent Init calls use singleflight (only one initialization happens) + +#### Graceful Shutdown with Timeout + +Shutdown is a graceful best-effort operation that returns an error if cleanup doesn't complete within the context +deadline: + +```go +ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) +defer cancel() + +if err := openfeature.ShutdownWithContext(ctx); err != nil { + // Error means cleanup timed out, but provider is still logically shut down + log.Printf("Shutdown timeout: %v (cleanup continuing in background)", err) +} +``` + +**Shutdown Behavior:** + +The provider is **immediately** marked as shut down (all new operations fail with `PROVIDER_NOT_READY`), then cleanup +happens within the context deadline: + +1. **Within Deadline:** Complete cleanup, return `nil` +2. **After Deadline:** Log warnings, return `ctx.Err()` (context.DeadlineExceeded), continue cleanup in background + +**Return Values:** + +- `nil` - shutdown completed successfully within timeout +- `context.DeadlineExceeded` - cleanup timed out (provider still logically shut down) +- `context.Canceled` - context was cancelled (provider still logically shut down) + +**Cleanup Timing:** + +- Event channel close: Immediate +- Monitoring goroutine: Up to 30 seconds to terminate +- Split SDK Destroy: Up to 1 hour in streaming mode (known SDK limitation) + +**Recommended Timeout:** 30 seconds minimum to allow monitoring goroutine to exit cleanly. + +**Important:** Even when an error is returned, the provider is logically shut down: + +- Provider state is atomically set to "shut down" immediately +- All new operations (Init, evaluations) will fail with PROVIDER_NOT_READY +- Background cleanup continues safely even after error is returned + +#### Provider Reusability + +**Important:** Once shut down, a provider instance cannot be reused. Attempting to initialize after shutdown returns an +error: + +```go +ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) +defer cancel() +_ = provider.ShutdownWithContext(ctx) + +// This will fail with error: "cannot initialize provider after shutdown" +initCtx, initCancel := context.WithTimeout(context.Background(), 15*time.Second) +defer initCancel() +err := openfeature.SetProviderWithContextAndWait(initCtx, provider) +``` + +To use a provider again after shutdown, create a new instance: + +```go +newProvider, _ := split.New("YOUR_API_KEY") +``` + +#### Thread Safety Guarantees + +The provider is fully thread-safe with the following guarantees: + +- **Concurrent Evaluations:** Multiple goroutines can safely call evaluation methods simultaneously +- **Evaluation During Shutdown:** In-flight evaluations complete safely before client destruction +- **Concurrent Init Calls:** Multiple Init calls use singleflight - only one initialization happens +- **Status Consistency:** Status() and Metrics() return consistent atomic state even during transitions +- **Factory Access:** Factory() can be called safely during concurrent operations + +### Provider Status + +The provider follows OpenFeature's state lifecycle with the following states: + +| State | When It Occurs | Evaluations Behavior | Status() Returns | +|--------------|-------------------------------------------------|-----------------------------------|--------------------| +| **NotReady** | After `New()`, before `Init()` completes | Return `PROVIDER_NOT_READY` error | `of.NotReadyState` | +| **Ready** | After successful `Init()` / `BlockUntilReady()` | Execute normally with Split SDK | `of.ReadyState` | +| **NotReady** | After `Shutdown()` called | Return `PROVIDER_NOT_READY` error | `of.NotReadyState` | + +**State Transitions:** + +``` +New() → NotReady + ↓ +Init() → Ready (if SDK becomes ready) + ↓ + └─→ NotReady (if Shutdown() called) + ↓ + [Terminal State - Cannot re-initialize] +``` + +**Important Notes:** + +- Once `Shutdown()` is called, the provider **cannot be re-initialized** - create a new instance instead +- `Init()` can fail due to timeout, invalid API key, or shutdown during initialization +- State transitions emit OpenFeature events (`PROVIDER_READY`, `PROVIDER_ERROR`, `PROVIDER_CONFIGURATION_CHANGED`) + +**Staleness Detection Limitation:** +The Split SDK's `IsReady()` method only indicates initial readiness and does not change when network connectivity is +lost. The SDK handles connectivity issues internally (switching between streaming and polling modes) but does not expose +this state. As a result, `PROVIDER_STALE` events are not emitted. When connectivity is lost, the SDK continues serving +cached data silently. See [CONTRIBUTING.md](CONTRIBUTING.md) for details on this limitation. + +**Check provider readiness:** + +```go +// Check via client (works for both default and named providers) +client := openfeature.NewClient("my-app") // or named domain like "tenant-1" +if client.State() == openfeature.ReadyState { + // Provider ready for evaluations +} + +// Get provider metadata +metadata := client.Metadata() +domain := metadata.Domain() // Client's domain name +``` + +**For diagnostics and monitoring:** + +```go +// Provider-specific health metrics +metrics := provider.Metrics() +// Returns map with: provider, initialized, status, splits_count, ready +``` + +### Known Limitations + +**Context Cancellation During Evaluation** + +Evaluation methods (`BooleanValue`, `StringValue`, etc.) accept a `context.Context` parameter but **cannot cancel +in-flight evaluations**. This is because the underlying Split SDK's `TreatmentWithConfig()` method does not support +context cancellation. + +**Impact:** + +- Context cancellation/timeout is only checked **before** calling the Split SDK +- Once evaluation starts, it runs to completion even if context expires +- In localhost mode: evaluations are fast (~microseconds), low risk +- In cloud mode: evaluations read from cache, typically <1ms, but network issues could cause delays + +**Affected operations:** + +- ✅ `InitWithContext` - respects context cancellation +- ✅ `ShutdownWithContext` - respects context timeout +- ❌ Flag evaluations - cannot cancel once started + +**Workarounds:** + +```go +// Option 1: Use HTTP-level timeouts (recommended) +cfg := conf.Default() +cfg.Advanced.HTTPTimeout = 5 * time.Second + +// Option 2: Set aggressive evaluation context timeout +ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) +defer cancel() +// Note: timeout only applies BEFORE evaluation starts +value, err := client.BooleanValue(ctx, "flag", false, evalCtx) +``` + +**Per-Evaluation Impression Control (Forward-Looking API)** + +`WithImpressionDisabled()` and `EvalOptions.ImpressionDisabled` are provided as forward-looking API surface for +per-evaluation impression control. The Split Go SDK does not currently support disabling impressions on individual +evaluations - only SDK-level impression modes (`OPTIMIZED`/`DEBUG`/`NONE`) configured at initialization time. + +When `ImpressionDisabled` is set, the provider logs a one-time info message per provider instance but does not enforce +the setting. This API will become functional when the Split Go SDK adds per-evaluation impression support. + +**Split SDK Destroy() Blocking (Streaming Mode)** + +In cloud/streaming mode, the Split SDK's `Destroy()` method can block for up to 1 hour due to SSE connection handling. +This is a known Split SDK limitation tracked +in [splitio/go-client#243](https://github.com/splitio/go-client/issues/243). + +**Impact:** During shutdown, cleanup may continue in background if context timeout expires. The provider is logically +shut down immediately (all new operations return defaults), only cleanup may be delayed. + +**Mitigation:** Use appropriate shutdown timeout (30s recommended): + +```go +ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) +defer cancel() +openfeature.ShutdownWithContext(ctx) +``` + +## Examples + +Complete working examples with detailed code: + +- **[localhost/](./examples/localhost/)** - Local development mode (YAML file, no API key required) +- **[cloud/](./examples/cloud/)** - Cloud mode with streaming updates and all flag types +- **[test/integration/](./test/integration/)** - Comprehensive integration test suite + +Run examples: + +```bash +task example-localhost # No API key needed +task example-cloud # Requires SPLIT_API_KEY +task test-integration # Full integration tests +``` + +## API + +### Flag Evaluation + +All methods require targeting key in evaluation context: + +```go +ctx := context.Background() +evalCtx := openfeature.NewEvaluationContext("user-123", map[string]any{ + "email": "user@example.com", + "plan": "premium", +}) + +// Boolean +enabled, err := client.BooleanValue(ctx, "new-feature", false, evalCtx) + +// String +theme, err := client.StringValue(ctx, "ui-theme", "light", evalCtx) + +// Number +maxRetries, err := client.IntValue(ctx, "max-retries", 3, evalCtx) +discount, err := client.FloatValue(ctx, "discount-rate", 0.0, evalCtx) + +// Object +result, err := client.ObjectValue(ctx, "flag-key", split.FlagSetResult{}, evalCtx) +``` + +### Object Evaluation - Mode-Specific Behavior + +Object evaluation returns `split.FlagSetResult` in both modes: + +```go +type FlagResult struct { + Config any // Parsed JSON config, or nil + Treatment string // Split treatment name (e.g., "on", "off", "v1") +} + +type FlagSetResult map[string]FlagResult +``` + +**Cloud Mode** (default: flag set evaluation): + +```go +// Default behavior: treats "my-flag-set" as a flag set name +result, _ := client.ObjectValue(ctx, "my-flag-set", split.FlagSetResult{}, evalCtx) +flags := result.(split.FlagSetResult) +for name, flag := range flags { + fmt.Printf("%s: %s\n", name, flag.Treatment) +} + +// Override: evaluate a single flag instead of a flag set +individualCtx := split.WithEvaluationMode(ctx, split.EvaluationModeIndividual) +result, _ = client.ObjectValue(individualCtx, "single-flag", split.FlagSetResult{}, evalCtx) +``` + +**Localhost Mode** (always individual flag evaluation): + +```go +result, _ := client.ObjectValue(ctx, "single-flag", split.FlagSetResult{}, evalCtx) +flags := result.(split.FlagSetResult) +flag := flags["single-flag"] +fmt.Println(flag.Treatment, flag.Config) +``` + +**Note:** Flag sets are NOT supported in localhost mode. `EvaluationModeSet` is silently ignored (always uses individual +evaluation). See [Evaluation Options](#evaluation-options) for details. + +### Evaluation Options + +Control per-request evaluation behavior via `context.Context`: + +```go +// Force individual flag evaluation in cloud mode (instead of flag set) +individualCtx := split.WithEvaluationMode(ctx, split.EvaluationModeIndividual) +result, _ := client.ObjectValue(individualCtx, "single-flag", split.FlagSetResult{}, evalCtx) + +// Force flag set evaluation (explicit, same as cloud default) +setCtx := split.WithEvaluationMode(ctx, split.EvaluationModeSet) +result, _ = client.ObjectValue(setCtx, "my-flag-set", split.FlagSetResult{}, evalCtx) + +// Set multiple evaluation options at once +optionsCtx := split.WithEvalOptions(ctx, split.EvalOptions{ + Mode: split.EvaluationModeIndividual, + ImpressionDisabled: true, // Forward-looking API (see note below) +}) +``` + +**Evaluation Modes:** + +| Mode | Cloud Behavior | Localhost Behavior | +|-------------------------------|-------------------------|------------------------| +| `EvaluationModeDefault` (`""`)| Flag set evaluation | Individual evaluation | +| `EvaluationModeSet` | Flag set evaluation | Ignored (individual) | +| `EvaluationModeIndividual` | Individual evaluation | Individual evaluation | + +**Note:** `EvaluationModeSet` is silently ignored in localhost mode because the Split SDK's localhost mode does not +support flag sets. A debug-level log message is emitted when this occurs. + +**ImpressionDisabled** (forward-looking API): The `WithImpressionDisabled()` helper and `ImpressionDisabled` field are +provided for future compatibility with Split SDK per-evaluation impression control. Currently logged but not enforced. +See [Known Limitations](#known-limitations). + +### Extracting Configuration Metadata + +All `*ValueDetails` methods return evaluation metadata including flag metadata: + +```go +details, err := client.StringValueDetails(ctx, "ui-theme", "light", evalCtx) + +// Standard fields +value := details.Value // Evaluated value: "dark" (for strings, same as treatment) +treatment := details.Variant // Split treatment name: "dark", "light", etc. +reason := details.Reason // TARGETING_MATCH, DEFAULT, ERROR + +// Extract flag metadata (configurations attached to treatments) +// All config types are wrapped in FlagMetadata["value"] for consistency +if configValue, ok := details.FlagMetadata["value"]; ok { + // Object config: {"bgColor": "#000", "fontSize": 14} + if configMap, ok := configValue.(map[string]any); ok { + bgColor := configMap["bgColor"] + fontSize := configMap["fontSize"] + } + // Primitive config: 42 + if num, ok := configValue.(float64); ok { + // Use primitive value + } + // Array config: ["a", "b", "c"] + if arr, ok := configValue.([]any); ok { + // Use array + } } -openfeature.SetProvider(provider) ``` -## Use of OpenFeature with Split -After the initial setup you can use OpenFeature according to their [documentation](https://docs.openfeature.dev/docs/reference/concepts/evaluation-api/). +### Evaluation Reasons + +| Reason | Description | +|-------------------|---------------------------------------------------------------------------| +| `TARGETING_MATCH` | Flag successfully evaluated | +| `DEFAULT` | Flag not found, returned default value | +| `ERROR` | Evaluation error (missing targeting key, provider not ready, parse error) | + +### Error Codes + +Provider implements OpenFeature error codes. All errors return default value: + +- `PROVIDER_NOT_READY` - Provider not initialized +- `FLAG_NOT_FOUND` - Flag doesn't exist in Split +- `PARSE_ERROR` - Treatment can't parse to requested type +- `TARGETING_KEY_MISSING` - No targeting key in context +- `INVALID_CONTEXT` - Malformed evaluation context +- `GENERAL` - Context canceled/timeout or other errors + +### Default Value Behavior + +OpenFeature's design philosophy: **evaluations never return Go errors**. Instead, they return the default value you +provide with resolution details indicating what happened. + +**When Split SDK Returns "control" Treatment:** + +The Split SDK returns a special `"control"` treatment to indicate evaluation failure. Our provider translates this to +OpenFeature's default value pattern: + +| Condition | Split SDK Returns | Caller Receives | Resolution Details | +|----------------------------|-------------------|-----------------|---------------------------------------------------| +| Flag doesn't exist | `"control"` | Default value | `Reason: DEFAULT`
`Error: FLAG_NOT_FOUND` | +| Provider not initialized | `"control"` | Default value | `Reason: ERROR`
`Error: PROVIDER_NOT_READY` | +| Provider shut down | `"control"` | Default value | `Reason: ERROR`
`Error: PROVIDER_NOT_READY` | +| Targeting key missing | `"control"` | Default value | `Reason: ERROR`
`Error: TARGETING_KEY_MISSING` | +| Context canceled | `"control"` | Default value | `Reason: ERROR`
`Error: GENERAL` | +| Network error (cloud mode) | `"control"` | Default value | `Reason: DEFAULT`
`Error: FLAG_NOT_FOUND` | + +**Example:** + +```go +// Flag doesn't exist in Split +enabled, err := client.BooleanValue(ctx, "nonexistent-flag", false, evalCtx) +// Result: +// - enabled = false (your default value) +// - err = nil (OpenFeature doesn't return errors) + +// To check what happened, use *ValueDetails methods: +details, err := client.BooleanValueDetails(ctx, "nonexistent-flag", false, evalCtx) +// - details.Value = false +// - details.Reason = of.DefaultReason +// - details.ErrorCode = of.FlagNotFoundCode +// - details.ErrorMessage = "flag not found" +``` + +**Key Points:** + +- Your application continues running normally with safe default values +- No panic, no nil pointers, no error handling required for normal operation +- Use `*ValueDetails` methods when you need to distinguish between success and fallback +- This design enables graceful degradation during outages or misconfigurations + +### Event Tracking + +Track user actions for experimentation and analytics: -One important note is that the Split Provider **requires a targeting key** to be set. Often times this should be set when evaluating the value of a flag by [setting an EvaluationContext](https://docs.openfeature.dev/docs/reference/concepts/evaluation-context) which contains the targeting key. An example flag evaluation is ```go -client := openfeature.NewClient("CLIENT_NAME"); +evalCtx := openfeature.NewEvaluationContext("user-123", nil) -evaluationContext := openfeature.NewEvaluationContext("TARGETING_KEY", nil) -boolValue := client.BooleanValue(nil, "boolFlag", false, evaluationContext) +// Basic tracking with value +details := openfeature.NewTrackingEventDetails(99.99) +client.Track(ctx, "purchase_completed", evalCtx, details) + +// Tracking with custom traffic type +evalCtxAccount := openfeature.NewEvaluationContext("account-456", map[string]any{ + "trafficType": "account", // Optional, defaults to "user" +}) +client.Track(ctx, "subscription_created", evalCtxAccount, details) + +// Tracking with properties +purchaseDetails := openfeature.NewTrackingEventDetails(149.99). + Add("currency", "USD"). + Add("item_count", 3). + Add("category", "electronics") +client.Track(ctx, "purchase", evalCtx, purchaseDetails) ``` -If the same targeting key is used repeatedly, the evaluation context may be set at the client level + +**Supported Property Types:** + +The Split SDK accepts the following property value types: + +| Type | Supported | Example | +|----------------------------|-----------|----------------------------| +| `string` | ✅ | `Add("currency", "USD")` | +| `bool` | ✅ | `Add("is_premium", true)` | +| `int`, `int32`, `int64` | ✅ | `Add("item_count", 3)` | +| `uint`, `uint32`, `uint64` | ✅ | `Add("quantity", uint(5))` | +| `float32`, `float64` | ✅ | `Add("price", 99.99)` | +| `nil` | ✅ | `Add("optional", nil)` | +| Arrays, maps, structs | ❌ | Silently set to `nil` | + +**⚠️ Important:** Unsupported types (arrays, maps, nested objects) are **silently set to `nil`** by the Split SDK - no +error is returned. Always use primitive types for event properties. + +**Parameters:** + +- `trackingEventName`: Event name (e.g., "checkout", "signup") +- `evaluationContext`: Contains targeting key and optional `trafficType` attribute +- `details`: Event value and custom properties + +**Traffic Type:** + +- Defaults to `"user"` if not specified +- Set via `trafficType` attribute in evaluation context +- Must match a defined traffic type in Split + +**Localhost Mode:** Track events are accepted but not persisted (no server to send them to). Code using `Track()` runs +unchanged in local development. + +**View Events:** Track events appear in Split Data Hub (Live Tail tab). + +### Track Options + +Control per-request tracking behavior via `context.Context`: + +```go +// Track with metric value (standard - value sent to Split for sum/average metrics) +details := openfeature.NewTrackingEventDetails(99.99) +client.Track(ctx, "purchase", evalCtx, details) + +// Track without metric value (count-only event) +// Sends nil to Split instead of 0, preventing pollution of sum/average metrics +noValueCtx := split.WithoutMetricValue(ctx) +countDetails := openfeature.NewTrackingEventDetails(0) // value ignored due to context option +client.Track(noValueCtx, "page_view", evalCtx, countDetails) +``` + +**Why `WithoutMetricValue`?** + +OpenFeature's `NewTrackingEventDetails(value)` requires a numeric value, but Split supports count-only events (no metric +value). Without this option, passing `0` would pollute sum/average metrics. `WithoutMetricValue` tells the provider to +send `nil` to Split's Track API, recording only the event count. + +### Event Handling + +Subscribe to provider lifecycle events: + ```go -evaluationContext := openfeature.NewEvaluationContext("TARGETING_KEY", nil) -client.SetEvaluationContext(context) +openfeature.AddHandler(openfeature.ProviderReady, func(details openfeature.EventDetails) { + log.Println("Provider ready") +}) + +openfeature.AddHandler(openfeature.ProviderConfigChange, func(details openfeature.EventDetails) { + log.Println("Configuration updated") +}) ``` -or at the OpenFeatureAPI level + +**Events:** + +- `PROVIDER_READY` - Provider initialized successfully +- `PROVIDER_CONFIG_CHANGE` - Flag configurations updated (detected via polling, default 30s, configurable via + `WithMonitoringInterval`) +- `PROVIDER_ERROR` - Initialization or runtime error + +**Event Limitations:** + +- `PROVIDER_STALE` events are not emitted due to Split SDK limitations. See [Provider Status](#provider-status) for + details. +- `PROVIDER_CONFIG_CHANGE` is detected by polling (default 30 seconds, configurable via `WithMonitoringInterval`, + minimum + 5 seconds), not via real-time SSE streaming. While the Split SDK receives changes instantly via SSE, it doesn't expose + a callback for configuration changes, so the provider polls `manager.Splits()` to detect changes. See + [CONTRIBUTING.md](CONTRIBUTING.md) for details. + +### Direct SDK Access + +**⚠️ Advanced Usage Only** + +The provider manages the Split SDK lifecycle (initialization, shutdown, cleanup). Direct factory access should only be +used for Split-specific features not available through OpenFeature. + +**Lifecycle Constraints:** + +- ❌ **DO NOT** call `factory.Client().Destroy()` - provider owns lifecycle +- ❌ **DO NOT** call `factory.Client().BlockUntilReady()` - use `client.State()` instead (see [Provider Status](#provider-status)) +- ⚠️ Factory is only valid between `Init` and `Shutdown` +- ⚠️ After `Shutdown()`, factory and client are destroyed + +**Example:** + ```go -evaluationContext := openfeature.NewEvaluationContext("TARGETING_KEY", nil) -openfeature.SetEvaluationContext(context) -```` -If the context was set at the client or api level, it is not required to provide it during flag evaluation. +factory := provider.Factory() +// Use factory for Split-specific features not available in OpenFeature +``` + +See [Split Go SDK documentation](https://github.com/splitio/go-client) for available methods. + +## Testing + +**Unit tests:** Use OpenFeature test provider, not Split provider. -## Submitting issues - -The Split team monitors all issues submitted to this [issue tracker](https://github.com/splitio/split-openfeature-provider-go/issues). We encourage you to use this issue tracker to submit any bug reports, feedback, and feature enhancements. We'll do our best to respond in a timely manner. +**Integration tests:** Use localhost mode with YAML files. See [test/integration/](./test/integration/). + +**Provider tests:** + +```bash +task test # Run all tests +task test-race # Run with race detection +task test-coverage # Generate coverage report +``` + +## Development + +Development workflow managed via [Taskfile](./Taskfile.yml): + +```bash +task # List all tasks +task example-localhost # Run localhost example +task example-cloud # Run cloud example +task test-integration # Run integration tests +task lint # Run linters +``` + +## Logging + +Provider uses `slog` for structured logging. Configure via `slog.SetDefault()` or `split.WithLogger()` option. + +**Source attribution:** + +- `source="split-provider"` - Provider logs +- `source="split-sdk"` - Split SDK logs +- `source="openfeature-sdk"` - OpenFeature SDK logs (via hooks) + +See [examples/](./examples/) for logging configuration patterns. ## Contributing -Please see [Contributors Guide](CONTRIBUTORS-GUIDE.md) to find all you need to submit a Pull Request (PR). + +Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing requirements, and PR +process. ## License -Licensed under the Apache License, Version 2.0. See: [Apache License](http://www.apache.org/licenses/). - -## 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. Split’s fine-grained management, real-time monitoring, and data-driven experimentation ensure that new features will improve the customer experience without breaking or degrading performance. Companies like Twilio, Salesforce, GoDaddy and WePay trust Split to power their feature delivery. - -To learn more about Split, contact hello@split.io, or get started with feature flags for free at https://www.split.io/signup. - -Split has built and maintains SDKs for: - -* Java [Github](https://github.com/splitio/java-client) [Docs](https://help.split.io/hc/en-us/articles/360020405151-Java-SDK) -* Javascript [Github](https://github.com/splitio/javascript-client) [Docs](https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK) -* Node [Github](https://github.com/splitio/javascript-client) [Docs](https://help.split.io/hc/en-us/articles/360020564931-Node-js-SDK) -* .NET [Github](https://github.com/splitio/dotnet-client) [Docs](https://help.split.io/hc/en-us/articles/360020240172--NET-SDK) -* Ruby [Github](https://github.com/splitio/ruby-client) [Docs](https://help.split.io/hc/en-us/articles/360020673251-Ruby-SDK) -* PHP [Github](https://github.com/splitio/php-client) [Docs](https://help.split.io/hc/en-us/articles/360020350372-PHP-SDK) -* Python [Github](https://github.com/splitio/python-client) [Docs](https://help.split.io/hc/en-us/articles/360020359652-Python-SDK) -* GO [Github](https://github.com/splitio/go-client) [Docs](https://help.split.io/hc/en-us/articles/360020093652-Go-SDK) -* Android [Github](https://github.com/splitio/android-client) [Docs](https://help.split.io/hc/en-us/articles/360020343291-Android-SDK) -* iOS [Github](https://github.com/splitio/ios-client) [Docs](https://help.split.io/hc/en-us/articles/360020401491-iOS-SDK) - -For a comprehensive list of open source projects visit our [Github page](https://github.com/splitio?utf8=%E2%9C%93&query=%20only%3Apublic%20). - -**Learn more about Split:** - -Visit [split.io/product](https://www.split.io/product) for an overview of Split, or visit our documentation at [help.split.io](http://help.split.io) for more detailed information. +Apache License 2.0. See [LICENSE](http://www.apache.org/licenses/LICENSE-2.0). + +## Links + +- [Split.io](https://www.split.io/) +- [OpenFeature](https://openfeature.dev/) +- [API Documentation](https://pkg.go.dev/github.com/splitio/split-openfeature-provider-go/v2) +- [Issue Tracker](https://github.com/splitio/split-openfeature-provider-go/issues) diff --git a/Taskfile.yml b/Taskfile.yml new file mode 100644 index 0000000..a42c011 --- /dev/null +++ b/Taskfile.yml @@ -0,0 +1,366 @@ +version: '3' + +# Split OpenFeature Provider - Task Runner +# Run 'task' or 'task help' for usage information + +# ============================================================================= +# Global Configuration +# ============================================================================= + +output: prefixed +silent: true +dotenv: ['.env.local'] + +# ============================================================================= +# Variables +# ============================================================================= + +vars: + COVERAGE_FILE: coverage.out + COVERAGE_THRESHOLD: 70 + LINT_TIMEOUT: 5m + +# ============================================================================= +# Default & Help +# ============================================================================= + +tasks: + default: + desc: Show available tasks + aliases: [list, ls] + cmds: + - task --list + + help: + desc: Show help and common workflows + aliases: [h, '?'] + cmds: + - | + echo "Split OpenFeature Provider - Task Runner" + echo "========================================" + echo "" + echo "Quick Start:" + echo " task install-tools Install development tools" + echo " task test Run tests" + echo "" + echo "Development Workflow:" + echo " task check Run all quality checks (lint + test + coverage)" + echo " task pre-commit Quick checks before committing" + echo " task ci Full CI checks before PR" + echo "" + echo "Code Quality:" + echo " task lint Run linter" + echo " task lint-fix Run linter with auto-fix" + echo " task fmt Format code" + echo " task vet Run go vet" + echo "" + echo "Testing:" + echo " task test Run unit tests with coverage" + echo " task test-race Run with race detection (no coverage)" + echo " task test-short Run unit tests (fast mode)" + echo " task test-coverage Show coverage report" + echo " task coverage-check Verify coverage >= {{.COVERAGE_THRESHOLD}}%" + echo "" + echo "Examples:" + echo " task example-localhost Offline mode with YAML (no account)" + echo " task example-cloud Cloud mode (requires SPLIT_API_KEY)" + echo "" + echo "Integration Testing:" + echo " task test-integration Auto-selects localhost or cloud mode" + echo " task test-cloud Cloud-only features" + echo "" + echo "Code Generation:" + echo " task generate-mocks Generate mock implementations (mockery v3)" + echo "" + echo "Run 'task --list' to see all available tasks" + + # =========================================================================== + # Workflow Tasks + # =========================================================================== + + check: + desc: Run all quality checks (lint, test, coverage) + aliases: [c] + cmds: + - task: lint + - task: test + - task: coverage-check + + ci: + desc: Run full CI pipeline (use before submitting PR) + cmds: + - echo "Running CI checks..." + - task: fmt-check + - task: lint + - task: vet + - task: test + - task: coverage-check + - echo "All CI checks passed!" + + pre-commit: + desc: Run pre-commit checks (format, lint, quick test) + aliases: [pc] + cmds: + - task: fmt + - task: lint + - task: test-short + + pre-push: + desc: Run pre-push checks (full CI) + aliases: [pp] + cmds: + - task: ci + + # =========================================================================== + # Build Tasks + # =========================================================================== + + build: + desc: Build the provider + aliases: [b] + method: checksum + sources: + - '**/*.go' + - go.mod + - go.sum + cmds: + - go build -v ./... + + clean: + desc: Clean build artifacts and caches + cmds: + - rm -f {{.COVERAGE_FILE}} + - rm -rf .task/ + - go clean -cache -testcache + + # =========================================================================== + # Testing Tasks + # =========================================================================== + + test: + desc: Run unit tests with race detector and coverage + aliases: [t] + cmds: + - go test -v -race -coverprofile={{.COVERAGE_FILE}} -covermode=atomic $(go list ./... | grep -v /examples/ | grep -v /test/) + - task: _update-coverage-badge + + test-race: + desc: Run unit tests with race detector (no coverage) + aliases: [tr] + cmds: + - go test -v -race -count=1 $(go list ./... | grep -v /examples/ | grep -v /test/) + + test-short: + desc: Run unit tests in short mode (fast) + aliases: [ts] + cmds: + - go test -v -short $(go list ./... | grep -v /examples/ | grep -v /test/) + + # =========================================================================== + # Coverage Tasks + # =========================================================================== + + coverage: + desc: Generate and display coverage report + aliases: [cov, test-coverage] + deps: [test] + cmds: + - go tool cover -func={{.COVERAGE_FILE}} + + coverage-check: + desc: Verify coverage meets {{.COVERAGE_THRESHOLD}}% threshold + aliases: [cc] + deps: [test] + cmds: + - | + COVERAGE=$(go tool cover -func={{.COVERAGE_FILE}} | grep total | awk '{print $3}' | sed 's/%//') + echo "Coverage: $COVERAGE% (threshold: {{.COVERAGE_THRESHOLD}}%)" + if [ $(echo "$COVERAGE < {{.COVERAGE_THRESHOLD}}" | bc) -eq 1 ]; then + echo "FAIL: Coverage is below threshold" + exit 1 + fi + echo "PASS: Coverage meets threshold" + + coverage-html: + desc: Open coverage report in browser + deps: [test] + cmds: + - go tool cover -html={{.COVERAGE_FILE}} + + # =========================================================================== + # Code Quality Tasks + # =========================================================================== + + lint: + desc: Run golangci-lint + aliases: [l] + method: checksum + sources: + - '**/*.go' + - .golangci.yml + cmds: + - golangci-lint run --timeout {{.LINT_TIMEOUT}} + + lint-fix: + desc: Run golangci-lint with auto-fix + aliases: [lf] + cmds: + - golangci-lint run --fix --timeout {{.LINT_TIMEOUT}} + + fmt: + desc: Format code with gofmt + aliases: [f] + cmds: + - gofmt -s -w . + + fmt-check: + desc: Check code formatting (no changes) + aliases: [fc] + cmds: + - | + UNFORMATTED=$(gofmt -l .) + if [ -n "$UNFORMATTED" ]; then + echo "Unformatted files:" + echo "$UNFORMATTED" + exit 1 + fi + echo "All files formatted correctly" + + vet: + desc: Run go vet + aliases: [v] + method: checksum + sources: + - '**/*.go' + cmds: + - go vet ./... + + # =========================================================================== + # Example Tasks + # =========================================================================== + + example-localhost: + desc: Run localhost example (offline YAML flags, no account needed) + aliases: [el] + dir: examples/localhost + cmds: + - go run main.go + + example-cloud: + desc: Run cloud example (requires SPLIT_API_KEY in .env.local) + aliases: [ec] + dir: examples/cloud + preconditions: + - sh: test -n "$SPLIT_API_KEY" + msg: "SPLIT_API_KEY not set. Create .env.local with SPLIT_API_KEY=your-key" + cmds: + - go run main.go + + # =========================================================================== + # Integration Testing Tasks + # =========================================================================== + + test-integration: + desc: Run integration tests (auto-selects localhost or cloud mode) + aliases: [ti] + dir: test/integration + cmds: + - go run . + + test-cloud: + desc: Run cloud-only integration tests (requires SPLIT_API_KEY) + aliases: [tc] + dir: test/advanced + preconditions: + - sh: test -n "$SPLIT_API_KEY" + msg: "SPLIT_API_KEY not set. Create .env.local with SPLIT_API_KEY=your-key" + cmds: + - go run main.go + + # =========================================================================== + # Dependency Management Tasks + # =========================================================================== + + deps-tidy: + desc: Tidy go.mod and go.sum + aliases: [tidy] + cmds: + - go mod tidy + + deps-update: + desc: Update all dependencies to latest versions + aliases: [update] + cmds: + - echo "Updating dependencies..." + - go get -u ./... + - go mod tidy + - echo "Done. Run 'task test' to verify." + + # =========================================================================== + # Code Generation Tasks + # =========================================================================== + + generate-mocks: + desc: Generate mock implementations using mockery v3 + aliases: [mocks] + method: checksum + sources: + - client.go + generates: + - mock_client_test.go + cmds: + - echo "Generating mocks..." + - mockery + - echo "Done. Mock files generated." + + # =========================================================================== + # Tool Management Tasks + # =========================================================================== + + install-tools: + desc: Install required development tools + aliases: [tools] + cmds: + - echo "Installing development tools..." + - brew install golangci-lint + - brew install mockery + - echo "Done!" + + check-tools: + desc: Verify required tools are installed + cmds: + - | + echo "Checking tools..." + MISSING="" + if ! command -v golangci-lint &> /dev/null; then + echo "[x] golangci-lint - not installed" + MISSING="yes" + else + echo "[ok] golangci-lint" + fi + if ! command -v mockery &> /dev/null; then + echo "[x] mockery - not installed" + MISSING="yes" + else + echo "[ok] mockery" + fi + if [ -n "$MISSING" ]; then + echo "" + echo "Run 'task install-tools' to install missing tools" + exit 1 + fi + echo "" + echo "All tools installed!" + + # =========================================================================== + # Internal Tasks + # =========================================================================== + + _update-coverage-badge: + internal: true + cmds: + - | + COVERAGE=$(go tool cover -func={{.COVERAGE_FILE}} | grep total | awk '{print $3}' | sed 's/%//') + sed -i.bak "s/coverage-[0-9.]*%25/coverage-$COVERAGE%25/g" README.md + rm -f README.md.bak + echo "Coverage badge updated to $COVERAGE%" diff --git a/benchmark_test.go b/benchmark_test.go new file mode 100644 index 0000000..b53b9e1 --- /dev/null +++ b/benchmark_test.go @@ -0,0 +1,166 @@ +package split + +import ( + "context" + "testing" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/conf" + "github.com/splitio/go-toolkit/v5/logging" +) + +// BenchmarkBooleanEvaluation benchmarks single boolean flag evaluation performance. +func BenchmarkBooleanEvaluation(b *testing.B) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + if err != nil { + b.Fatalf("Failed to create provider: %v", err) + } + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + if err != nil { + b.Fatalf("Failed to initialize provider: %v", err) + } + + flatCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: "bench-user", + } + + b.ResetTimer() + for i := 0; i < b.N; i++ { + _ = provider.BooleanEvaluation(context.TODO(), flagSomeOther, false, flatCtx) + } +} + +// BenchmarkStringEvaluation benchmarks single string flag evaluation performance. +func BenchmarkStringEvaluation(b *testing.B) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + if err != nil { + b.Fatalf("Failed to create provider: %v", err) + } + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + if err != nil { + b.Fatalf("Failed to initialize provider: %v", err) + } + + flatCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: "bench-user", + } + + b.ResetTimer() + for i := 0; i < b.N; i++ { + _ = provider.StringEvaluation(context.TODO(), flagSomeOther, "default", flatCtx) + } +} + +// BenchmarkConcurrentEvaluations benchmarks concurrent flag evaluations. +func BenchmarkConcurrentEvaluations(b *testing.B) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + if err != nil { + b.Fatalf("Failed to create provider: %v", err) + } + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + if err != nil { + b.Fatalf("Failed to initialize provider: %v", err) + } + + flatCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: "bench-user", + } + + b.ResetTimer() + b.RunParallel(func(pb *testing.PB) { + for pb.Next() { + _ = provider.BooleanEvaluation(context.TODO(), flagSomeOther, false, flatCtx) + } + }) +} + +// BenchmarkProviderInitialization measures provider initialization time. +func BenchmarkProviderInitialization(b *testing.B) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + b.ResetTimer() + for i := 0; i < b.N; i++ { + provider, err := New("localhost", WithSplitConfig(cfg)) + if err != nil { + b.Fatalf("Failed to create provider: %v", err) + } + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + if err != nil { + b.Fatalf("Failed to initialize provider: %v", err) + } + + _ = provider.ShutdownWithContext(context.Background()) + } +} + +// BenchmarkAttributeHeavyEvaluation measures evaluation performance with many attributes. +func BenchmarkAttributeHeavyEvaluation(b *testing.B) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + if err != nil { + b.Fatalf("Failed to create provider: %v", err) + } + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + if err != nil { + b.Fatalf("Failed to initialize provider: %v", err) + } + + flatCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: "bench-user", + "email": "user@example.com", + "plan": "enterprise", + "region": "us-east-1", + "org_id": "org-12345", + "user_id": "user-67890", + "account_type": "premium", + "feature_flags_enabled": true, + "beta_tester": true, + "signup_date": "2024-01-15", + "last_login": "2025-01-18", + "session_count": 42, + "total_spend": 1299.99, + "conversion_rate": 0.25, + "engagement_score": 87.5, + "device_type": "desktop", + "browser": "chrome", + "os": "macos", + "language": "en-US", + "timezone": "America/New_York", + } + + b.ResetTimer() + for i := 0; i < b.N; i++ { + _ = provider.BooleanEvaluation(context.TODO(), flagSomeOther, false, flatCtx) + } +} diff --git a/client.go b/client.go new file mode 100644 index 0000000..2fb5704 --- /dev/null +++ b/client.go @@ -0,0 +1,26 @@ +package split + +import "github.com/splitio/go-client/v6/splitio/client" + +// Compile-time check that *client.SplitClient satisfies Client. +var _ Client = (*client.SplitClient)(nil) + +// Client defines the Split SDK client methods used by this provider. +// This interface enables dependency injection for testing (mock generation via mockery). +// Method signatures match *client.SplitClient exactly (verified by compile-time check above). +type Client interface { + // TreatmentWithConfig evaluates a single flag and returns the treatment with optional JSON config. + TreatmentWithConfig(key interface{}, featureFlagName string, attributes map[string]interface{}) client.TreatmentResult + + // TreatmentsWithConfigByFlagSet evaluates all flags in a flag set. + TreatmentsWithConfigByFlagSet(key interface{}, flagSet string, attributes map[string]interface{}) map[string]client.TreatmentResult + + // Track sends a tracking event to Split for analytics. + Track(key string, trafficType string, eventType string, value interface{}, properties map[string]interface{}) error + + // BlockUntilReady blocks until the SDK is ready or the timeout (seconds) expires. + BlockUntilReady(timer int) error + + // Destroy shuts down the SDK client and releases resources. + Destroy() +} diff --git a/concurrency_test.go b/concurrency_test.go new file mode 100644 index 0000000..e8962c6 --- /dev/null +++ b/concurrency_test.go @@ -0,0 +1,184 @@ +package split + +import ( + "context" + "fmt" + "strings" + "sync" + "testing" + "time" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/conf" + "github.com/splitio/go-toolkit/v5/logging" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestConcurrentEvaluations tests thread safety with concurrent evaluations. +func TestConcurrentEvaluations(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + + ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + err = openfeature.SetProviderWithContextAndWait(ctx, provider) + require.NoError(t, err, "Failed to set provider") + + defer func() { + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 30*time.Second) + defer shutdownCancel() + _ = openfeature.ShutdownWithContext(shutdownCtx) + }() + + const numGoroutines = 50 + const numEvaluations = 100 + + var wg sync.WaitGroup + errors := make(chan error, numGoroutines) + + for i := 0; i < numGoroutines; i++ { + wg.Add(1) + go func(id int) { + defer wg.Done() + ofClient := openfeature.NewClient("concurrent-test") + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + for j := 0; j < numEvaluations; j++ { + _, err := ofClient.BooleanValue( + context.TODO(), + flagSomeOther, + false, + evalCtx, + ) + if err != nil && !strings.Contains(err.Error(), "FLAG_NOT_FOUND") { + errors <- fmt.Errorf("goroutine %d iteration %d: %w", id, j, err) + return + } + + _, err = ofClient.StringValue( + context.TODO(), + flagSomeOther, + "default", + evalCtx, + ) + if err != nil && !strings.Contains(err.Error(), "FLAG_NOT_FOUND") { + errors <- fmt.Errorf("goroutine %d iteration %d: %w", id, j, err) + return + } + } + }(i) + } + + wg.Wait() + close(errors) + + for err := range errors { + t.Errorf("Concurrent evaluation error: %v", err) + } +} + +// TestConcurrentInitShutdown tests race conditions when Init and Shutdown are called concurrently. +func TestConcurrentInitShutdown(t *testing.T) { + if testing.Short() { + t.Skip("skipping in short mode") + } + + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 1 + + const iterations = 2 + for i := 0; i < iterations; i++ { + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + var wg sync.WaitGroup + const concurrency = 3 + + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + + for j := 0; j < concurrency; j++ { + wg.Add(1) + go func() { + defer wg.Done() + _ = provider.InitWithContext(ctx, openfeature.NewEvaluationContext("", nil)) + }() + } + + wg.Add(1) + go func() { + defer wg.Done() + time.Sleep(10 * time.Millisecond) + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer shutdownCancel() + _ = provider.ShutdownWithContext(shutdownCtx) + }() + + wg.Wait() + + assert.Equal(t, openfeature.NotReadyState, provider.Status(), "Provider should be NotReady after shutdown") + } +} + +// TestEventChannelOverflow tests behavior when event channel buffer is full. +func TestEventChannelOverflow(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + eventChan := provider.EventChannel() + + const eventsToEmit = 150 + const bufferSize = 100 + + for i := 0; i < eventsToEmit; i++ { + select { + case <-eventChan: + // Drain one event to make room + default: + // Channel full or empty + } + } + + done := make(chan bool) + go func() { + status := provider.Status() + assert.Equal(t, openfeature.ReadyState, status, "Provider should still be ready") + done <- true + }() + + select { + case <-done: + // Success - operation completed without blocking + case <-time.After(2 * time.Second): + t.Fatal("Event emission appears to be blocking") + } + + drained := 0 + for { + select { + case <-eventChan: + drained++ + case <-time.After(10 * time.Millisecond): + goto doneLabel + } + } +doneLabel: + assert.LessOrEqual(t, drained, bufferSize, "Should not have more events than buffer size") +} diff --git a/config.go b/config.go new file mode 100644 index 0000000..04c1024 --- /dev/null +++ b/config.go @@ -0,0 +1,51 @@ +package split + +import "github.com/splitio/go-client/v6/splitio/conf" + +// TestConfig returns an optimized Split SDK configuration for tests and examples. +// This configuration minimizes timeouts, queue sizes, and sync intervals for faster +// execution while maintaining full functionality. +// +// Optimizations applied: +// - BlockUntilReady: 5 seconds (faster initialization timeout) +// - HTTPTimeout: 5 seconds (faster network failure detection) +// - ImpressionsMode: debug (sends all impressions, not batched) +// - Queue sizes: Reduced to 100 (faster event/impression flushing) +// - Bulk sizes: Reduced to 100 (smaller batches, faster submission) +// - Sync intervals: Set to minimums (faster updates) +// +// Usage: +// +// cfg := split.TestConfig() +// cfg.SplitFile = "./split.yaml" // For localhost mode +// provider, err := split.New(apiKey, split.WithSplitConfig(cfg)) +func TestConfig() *conf.SplitSdkConfig { + cfg := conf.Default() + + // Faster initialization timeout + cfg.BlockUntilReady = 5 + + // Faster network failure detection + cfg.Advanced.HTTPTimeout = 5 + + // Use debug mode for impression tracking (sends all impressions, 60s sync) + // Default "optimized" batches impressions which can delay visibility + cfg.ImpressionsMode = "debug" + + // Smaller queues for faster flushing in tests + cfg.Advanced.EventsQueueSize = 100 + cfg.Advanced.ImpressionsQueueSize = 100 + + // Smaller batches for faster submission + cfg.Advanced.EventsBulkSize = 100 + cfg.Advanced.ImpressionsBulkSize = 100 + + // Minimum sync intervals for faster updates + cfg.TaskPeriods.SplitSync = 5 // minimum: 5s + cfg.TaskPeriods.SegmentSync = 30 // minimum: 30s + cfg.TaskPeriods.ImpressionSync = 60 // minimum: 60s (debug mode) + cfg.TaskPeriods.EventsSync = 1 // minimum: 1s + cfg.TaskPeriods.TelemetrySync = 60 // reduced from 3600s + + return cfg +} diff --git a/constants.go b/constants.go new file mode 100644 index 0000000..d3c2b75 --- /dev/null +++ b/constants.go @@ -0,0 +1,68 @@ +package split + +import "time" + +const ( + // SDK Timeouts + + // defaultSDKTimeout is the default timeout in seconds for Split SDK initialization. + // Used as the default BlockUntilReady timeout when not configured. + defaultSDKTimeout = 10 + + // defaultInitTimeout is the default timeout for provider initialization when no BlockUntilReady is configured. + // Provides 5 seconds buffer beyond the defaultSDKTimeout (10s SDK + 5s buffer = 15s total). + defaultInitTimeout = 15 * time.Second + + // initTimeoutBuffer is added to BlockUntilReady to ensure initialization has time to complete gracefully. + initTimeoutBuffer = 5 * time.Second + + // defaultShutdownTimeout is the default timeout for provider shutdown operations. + // Allows time for monitoring goroutine cleanup, SDK destroy, and channel closes. + defaultShutdownTimeout = 30 * time.Second + + // Event Handling + + // eventChannelBuffer is the buffer size for the provider's event channel. + // Events are sent asynchronously to OpenFeature SDK handlers. + // Provides headroom for burst events. Overflow events are dropped (logged as warnings). + eventChannelBuffer = 128 + + // Monitoring + + // defaultMonitoringInterval is the default interval for checking split definition changes. + defaultMonitoringInterval = 30 * time.Second + + // minMonitoringInterval is the minimum allowed monitoring interval. + minMonitoringInterval = 5 * time.Second + + // Atomic States + + // shutdownStateActive indicates the provider has been shut down (atomic flag = 1). + shutdownStateActive = 1 + + // shutdownStateInactive indicates the provider is active (atomic flag = 0). + shutdownStateInactive = 0 + + // Split SDK Constants + + // controlTreatment is the treatment returned by Split SDK when a flag doesn't exist + // or evaluation fails. Used to detect missing flags and return defaults. + controlTreatment = "control" + + // treatmentOn is the conventional Split treatment for boolean "true". + treatmentOn = "on" + + // treatmentOff is the conventional Split treatment for boolean "false". + treatmentOff = "off" + + // OpenFeature Context Keys + + // TrafficTypeKey is the evaluation context attribute key for Split traffic type. + // Used by Track() to categorize events. Not used for flag evaluations + // (traffic type is configured per flag in Split dashboard). + TrafficTypeKey = "trafficType" + + // DefaultTrafficType is the default traffic type used when not specified in context. + // "user" is the most common traffic type for user-based targeting and tracking. + DefaultTrafficType = "user" +) diff --git a/doc.go b/doc.go new file mode 100644 index 0000000..91295e6 --- /dev/null +++ b/doc.go @@ -0,0 +1,42 @@ +// Package split provides an OpenFeature provider implementation for Split.io +// feature flags and A/B testing platform. +// +// # Basic Usage +// +// provider, err := split.New("YOUR_API_KEY") +// if err != nil { +// log.Fatal(err) +// } +// +// ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) +// defer cancel() +// if err := openfeature.SetProviderWithContextAndWait(ctx, provider); err != nil { +// log.Fatal(err) +// } +// +// client := openfeature.NewClient("my-app") +// evalCtx := openfeature.NewEvaluationContext("user-123", map[string]any{ +// "email": "user@example.com", +// }) +// enabled, _ := client.BooleanValue(context.Background(), "new-feature", false, evalCtx) +// +// Evaluations return default values on errors. Use *ValueDetails methods to +// distinguish success from fallback via Reason and ErrorCode fields. +// +// # Configuration +// +// cfg := conf.Default() +// cfg.BlockUntilReady = 15 +// +// provider, _ := split.New("YOUR_API_KEY", +// split.WithSplitConfig(cfg), +// split.WithLogger(logger), +// ) +// +// # Concurrency +// +// The provider is thread-safe. Multiple goroutines can evaluate flags +// concurrently. Shutdown waits for in-flight evaluations to complete. +// +// See README.md for complete documentation and examples. +package split diff --git a/docs/images/of_banner.png b/docs/images/of_banner.png new file mode 100644 index 0000000000000000000000000000000000000000..bf51611d4d75cb81001bc5d5b6af30eb63fd8894 GIT binary patch literal 214563 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 literal 0 HcmV?d00001 diff --git a/evaluation.go b/evaluation.go new file mode 100644 index 0000000..b7ee110 --- /dev/null +++ b/evaluation.go @@ -0,0 +1,505 @@ +package split + +import ( + "context" + "fmt" + "strconv" + "sync/atomic" + + of "github.com/open-feature/go-sdk/openfeature" +) + +// FlagResult represents a single flag evaluation result. +type FlagResult struct { + Config any // Parsed JSON config, or nil + Treatment string // Split treatment name (e.g., "on", "off", "v1") +} + +// FlagSetResult maps flag names to their evaluation results. +// Returned by ObjectEvaluation for flag sets and individual flag evaluations. +type FlagSetResult map[string]FlagResult + +// BooleanEvaluation evaluates a feature flag and returns a boolean value. +// +// The method converts Split treatments to boolean values: +// - "on" → true +// - "off" → false +// - Other values (including "true", "false", "1", "0") → parse error, returns def +// +// A targeting key must be present in ec. Additional attributes in ec +// are passed to Split for targeting rule evaluation. +// +// Context Cancellation Limitation: +// The ctx parameter is checked BEFORE evaluation starts, but the Split SDK does +// not support canceling in-flight evaluations. Once evaluation begins, it runs to +// completion. Evaluations are typically very fast (<1ms from cache), so this is +// rarely an issue. See README "Known Limitations" for details. +// +// Returns the def if: +// - Context is canceled or deadline exceeded (checked before evaluation) +// - Targeting key is missing +// - Flag is not found +// - Treatment cannot be parsed as boolean +func (p *Provider) BooleanEvaluation(ctx context.Context, flag string, def bool, ec of.FlattenedContext) of.BoolResolutionDetail { + targetingKey, ok := ec[of.TargetingKey].(string) + if !ok { + targetingKey = "" + } + p.logger.Debug("evaluating boolean flag", "flag", flag, "targeting_key", targetingKey, "default", def) + + if validationDetail := p.validateEvaluationContext(ctx, ec); validationDetail.Error() != nil { + p.logger.Debug("validation failed", "flag", flag, "error", validationDetail.ResolutionError.Error()) + return of.BoolResolutionDetail{ + Value: def, + ProviderResolutionDetail: validationDetail, + } + } + + result := p.evaluateTreatmentWithConfig(ctx, flag, ec) + p.logger.Debug("Split treatment received", "flag", flag, "treatment", result.Treatment, "has_config", result.Config != nil) + + if noTreatment(result.Treatment) { + p.logger.Debug("flag not found or control treatment", "flag", flag, "treatment", result.Treatment) + return of.BoolResolutionDetail{ + Value: def, + ProviderResolutionDetail: resolutionDetailNotFound(result.Treatment), + } + } + var value bool + switch result.Treatment { + case treatmentOn: + value = true + case treatmentOff: + value = false + default: + p.logger.Warn("cannot parse treatment as boolean", "flag", flag, "treatment", result.Treatment, "returning_default", def) + return of.BoolResolutionDetail{ + Value: def, + ProviderResolutionDetail: resolutionDetailParseError(result.Treatment), + } + } + p.logger.Debug("boolean evaluation successful", "flag", flag, "value", value, "treatment", result.Treatment) + return of.BoolResolutionDetail{ + Value: value, + ProviderResolutionDetail: p.resolutionDetailWithConfig(flag, result.Treatment, result.Config), + } +} + +// StringEvaluation evaluates a feature flag and returns a string value. +// +// The method returns the Split treatment directly as a string. This is the most +// common evaluation type as Split treatments are inherently string-based. +// +// A targeting key must be present in ec. Additional attributes in ec +// are passed to Split for targeting rule evaluation. +// +// Context Cancellation Limitation: +// The ctx parameter is checked BEFORE evaluation starts, but the Split SDK does +// not support canceling in-flight evaluations. See README "Known Limitations". +// +// Returns the def if: +// - Context is canceled or deadline exceeded (checked before evaluation) +// - Targeting key is missing +// - Flag is not found (treatment is "control" or empty) +func (p *Provider) StringEvaluation(ctx context.Context, flag, def string, ec of.FlattenedContext) of.StringResolutionDetail { + targetingKey, ok := ec[of.TargetingKey].(string) + if !ok { + targetingKey = "" + } + p.logger.Debug("evaluating string flag", "flag", flag, "targeting_key", targetingKey, "default", def) + + if validationDetail := p.validateEvaluationContext(ctx, ec); validationDetail.Error() != nil { + p.logger.Debug("validation failed", "flag", flag, "error", validationDetail.ResolutionError.Error()) + return of.StringResolutionDetail{ + Value: def, + ProviderResolutionDetail: validationDetail, + } + } + + result := p.evaluateTreatmentWithConfig(ctx, flag, ec) + p.logger.Debug("Split treatment received", "flag", flag, "treatment", result.Treatment, "has_config", result.Config != nil) + + if noTreatment(result.Treatment) { + p.logger.Debug("flag not found or control treatment", "flag", flag, "treatment", result.Treatment) + return of.StringResolutionDetail{ + Value: def, + ProviderResolutionDetail: resolutionDetailNotFound(result.Treatment), + } + } + p.logger.Debug("string evaluation successful", "flag", flag, "value", result.Treatment, "treatment", result.Treatment) + return of.StringResolutionDetail{ + Value: result.Treatment, + ProviderResolutionDetail: p.resolutionDetailWithConfig(flag, result.Treatment, result.Config), + } +} + +// FloatEvaluation evaluates a feature flag and returns a float64 value. +// +// The method parses the Split treatment as a floating-point number. This is useful +// for flags that control numeric values like pricing, weights, or percentages. +// +// A targeting key must be present in ec. Additional attributes in ec +// are passed to Split for targeting rule evaluation. +// +// Context Cancellation Limitation: +// The ctx parameter is checked BEFORE evaluation starts, but the Split SDK does +// not support canceling in-flight evaluations. See README "Known Limitations". +// +// Returns the def if: +// - Context is canceled or deadline exceeded (checked before evaluation) +// - Targeting key is missing +// - Flag is not found +// - Treatment cannot be parsed as a valid float64 +func (p *Provider) FloatEvaluation(ctx context.Context, flag string, def float64, ec of.FlattenedContext) of.FloatResolutionDetail { + targetingKey, ok := ec[of.TargetingKey].(string) + if !ok { + targetingKey = "" + } + p.logger.Debug("evaluating float flag", "flag", flag, "targeting_key", targetingKey, "default", def) + + if validationDetail := p.validateEvaluationContext(ctx, ec); validationDetail.Error() != nil { + p.logger.Debug("validation failed", "flag", flag, "error", validationDetail.ResolutionError.Error()) + return of.FloatResolutionDetail{ + Value: def, + ProviderResolutionDetail: validationDetail, + } + } + + result := p.evaluateTreatmentWithConfig(ctx, flag, ec) + p.logger.Debug("Split treatment received", "flag", flag, "treatment", result.Treatment, "has_config", result.Config != nil) + + if noTreatment(result.Treatment) { + p.logger.Debug("flag not found or control treatment", "flag", flag, "treatment", result.Treatment) + return of.FloatResolutionDetail{ + Value: def, + ProviderResolutionDetail: resolutionDetailNotFound(result.Treatment), + } + } + floatEvaluated, parseErr := strconv.ParseFloat(result.Treatment, 64) + if parseErr != nil { + p.logger.Warn("cannot parse treatment as float", "flag", flag, "treatment", result.Treatment, "error", parseErr, "returning_default", def) + return of.FloatResolutionDetail{ + Value: def, + ProviderResolutionDetail: resolutionDetailParseError(result.Treatment), + } + } + p.logger.Debug("float evaluation successful", "flag", flag, "value", floatEvaluated, "treatment", result.Treatment) + return of.FloatResolutionDetail{ + Value: floatEvaluated, + ProviderResolutionDetail: p.resolutionDetailWithConfig(flag, result.Treatment, result.Config), + } +} + +// IntEvaluation evaluates a feature flag and returns an int64 value. +// +// The method parses the Split treatment as a 64-bit integer. This is useful for +// flags that control counts, limits, timeouts, or other integer-based values. +// +// A targeting key must be present in ec. Additional attributes in ec +// are passed to Split for targeting rule evaluation. +// +// Context Cancellation Limitation: +// The ctx parameter is checked BEFORE evaluation starts, but the Split SDK does +// not support canceling in-flight evaluations. See README "Known Limitations". +// +// Returns the def if: +// - Context is canceled or deadline exceeded (checked before evaluation) +// - Targeting key is missing +// - Flag is not found +// - Treatment cannot be parsed as a valid int64 +func (p *Provider) IntEvaluation(ctx context.Context, flag string, def int64, ec of.FlattenedContext) of.IntResolutionDetail { + targetingKey, ok := ec[of.TargetingKey].(string) + if !ok { + targetingKey = "" + } + p.logger.Debug("evaluating int flag", "flag", flag, "targeting_key", targetingKey, "default", def) + + if validationDetail := p.validateEvaluationContext(ctx, ec); validationDetail.Error() != nil { + p.logger.Debug("validation failed", "flag", flag, "error", validationDetail.ResolutionError.Error()) + return of.IntResolutionDetail{ + Value: def, + ProviderResolutionDetail: validationDetail, + } + } + + result := p.evaluateTreatmentWithConfig(ctx, flag, ec) + p.logger.Debug("Split treatment received", "flag", flag, "treatment", result.Treatment, "has_config", result.Config != nil) + + if noTreatment(result.Treatment) { + p.logger.Debug("flag not found or control treatment", "flag", flag, "treatment", result.Treatment) + return of.IntResolutionDetail{ + Value: def, + ProviderResolutionDetail: resolutionDetailNotFound(result.Treatment), + } + } + intEvaluated, parseErr := strconv.ParseInt(result.Treatment, 10, 64) + if parseErr != nil { + p.logger.Warn("cannot parse treatment as int", "flag", flag, "treatment", result.Treatment, "error", parseErr, "returning_default", def) + return of.IntResolutionDetail{ + Value: def, + ProviderResolutionDetail: resolutionDetailParseError(result.Treatment), + } + } + p.logger.Debug("int evaluation successful", "flag", flag, "value", intEvaluated, "treatment", result.Treatment) + return of.IntResolutionDetail{ + Value: intEvaluated, + ProviderResolutionDetail: p.resolutionDetailWithConfig(flag, result.Treatment, result.Config), + } +} + +// ObjectEvaluation evaluates feature flags and returns them as a FlagSetResult. +// +// Mode of Operation: +// - Localhost Mode: Always treats flag parameter as a single flag name +// - Cloud Mode: Treats flag parameter as a flag set name by default; +// use WithEvaluationMode(EvaluationModeIndividual) to evaluate as a single flag +// +// Returns FlagSetResult (map[string]FlagResult) where each FlagResult contains: +// - Treatment: string (the Split treatment name) +// - Config: any (parsed JSON config, supports objects/arrays/primitives, or nil) +// +// Config values support any valid JSON type. Non-object configs (primitives, arrays) +// are returned as-is in the Config field. +// +// A targeting key must be present in ec. Additional attributes in ec +// are passed to Split for targeting rule evaluation. +// +// Context Cancellation Limitation: +// The ctx parameter is checked BEFORE evaluation starts, but the Split SDK does +// not support canceling in-flight evaluations. See README "Known Limitations". +// +// Returns def if context canceled (before evaluation), targeting key missing, or flag/flag set not found. +// +// Example: +// +// evalCtx := openfeature.NewEvaluationContext("user-123", nil) +// result, _ := client.ObjectValue(ctx, "ui-features", split.FlagSetResult{}, evalCtx) +// flags := result.(split.FlagSetResult) +// theme := flags["theme"] +// fmt.Println(theme.Treatment) // "dark" +// fmt.Println(theme.Config) // map[string]any{"primary": "#000"} +func (p *Provider) ObjectEvaluation(ctx context.Context, flag string, def any, ec of.FlattenedContext) of.InterfaceResolutionDetail { + targetingKey, ok := ec[of.TargetingKey].(string) + if !ok { + targetingKey = "" + } + p.logger.Debug("evaluating object flag", "flag", flag, "targeting_key", targetingKey) + + if validationDetail := p.validateEvaluationContext(ctx, ec); validationDetail.Error() != nil { + p.logger.Debug("validation failed", "flag", flag, "error", validationDetail.ResolutionError.Error()) + return of.InterfaceResolutionDetail{ + Value: def, + ProviderResolutionDetail: validationDetail, + } + } + + var results FlagSetResult + + // Get evaluation options from context + evalOpts := GetEvalOptions(ctx) + + // Determine evaluation mode + var mode EvaluationMode + if p.isLocalhostMode() { + // Localhost mode: always use individual (flag sets not supported in localhost mode) + if evalOpts.Mode == EvaluationModeSet { + p.logger.Warn("EvaluationModeSet ignored in localhost mode, using individual evaluation", + "requested_mode", evalOpts.Mode, + "flag", flag) + } + mode = EvaluationModeIndividual + } else { + // Cloud mode: respect EvaluationMode option, default to set + mode = evalOpts.Mode + if mode == EvaluationModeDefault { + mode = EvaluationModeSet + } + } + + // Execute based on resolved mode. + switch mode { + case EvaluationModeIndividual: + p.logger.Debug("evaluating single flag as object", "flag", flag) + results = p.evaluateSingleFlagAsObject(ctx, flag, ec) + case EvaluationModeSet: + p.logger.Debug("evaluating flag set", "flag_set", flag) + results = p.evaluateTreatmentsByFlagSet(ctx, flag, ec) + default: + p.logger.Error("unknown evaluation mode", "mode", mode, "flag", flag) + return of.InterfaceResolutionDetail{ + Value: def, + ProviderResolutionDetail: of.ProviderResolutionDetail{ + ResolutionError: of.NewGeneralResolutionError(fmt.Sprintf("unknown evaluation mode: %s", mode)), + Reason: of.ErrorReason, + }, + } + } + + if len(results) == 0 { + p.logger.Debug("no results returned", "flag", flag, "mode", mode) + return of.InterfaceResolutionDetail{ + Value: def, + ProviderResolutionDetail: resolutionDetailNotFound(""), + } + } + + p.logger.Debug("object evaluation successful", "flag", flag, "flag_count", len(results), "mode", mode) + // FlagMetadata is nil because configs are already embedded in each FlagResult.Config + // within the FlagSetResult value. Unlike scalar evaluations (where the value is the + // treatment and config needs FlagMetadata as a separate channel), ObjectEvaluation + // returns the full FlagSetResult containing per-flag configs directly. + return of.InterfaceResolutionDetail{ + Value: results, + ProviderResolutionDetail: of.ProviderResolutionDetail{ + Reason: of.TargetingMatchReason, + Variant: flag, + }, + } +} + +// Hooks returns the provider's hooks for OpenFeature lifecycle events. +// +// Currently returns nil (no hooks implemented). +func (p *Provider) Hooks() []of.Hook { + return nil +} + +// Track sends a tracking event to Split for experimentation and analytics. +// +// This method implements the Tracker interface, enabling the association of +// feature flag evaluations with subsequent actions or application states. +// The tracking data is used by Split for: +// - A/B testing and experimentation +// - Feature impact analysis +// - Business metrics correlation +// +// Parameters: +// - ctx: Context for the operation (checked for cancellation before tracking) +// - trackingEventName: The name of the event to track (e.g., "checkout", "signup") +// - evaluationContext: Contains the targeting key (user ID) and attributes +// - details: Optional tracking event details with value and custom attributes +// +// Required evaluation context: +// - targetingKey: The user identifier (required) +// - trafficType: The Split traffic type (optional, defaults to "user") +// +// The trackingEventName must match Split's event type constraints: +// - Maximum 80 characters +// - Starts with letter or number +// - Contains only letters, numbers, hyphens, underscores, periods, or colons +// +// The details.Value() is passed as the event value to Split. +// The details.Attributes() are passed as event properties to Split. +// +// Supported property types: string, bool, int, int32, int64, uint, uint32, uint64, +// float32, float64, and nil. Unsupported types (arrays, maps, structs) are silently +// set to nil by the Split SDK - no error is returned. +// +// If the provider is not ready, context is canceled, or the targeting key is empty, +// the call is logged and silently ignored (the Tracker interface defines no error return). +// +// Localhost Mode: Track events are accepted but not persisted (no server to send +// them to). This allows code using Track() to run unchanged in local development. +// +// Example: +// +// evalCtx := openfeature.NewEvaluationContext("user-123", map[string]any{ +// "trafficType": "account", // optional, defaults to "user" +// }) +// details := openfeature.NewTrackingEventDetails(99.99). +// Add("currency", "USD"). +// Add("item_count", 3) +// client.Track(ctx, "purchase", evalCtx, details) +func (p *Provider) Track(ctx context.Context, trackingEventName string, evaluationContext of.EvaluationContext, details of.TrackingEventDetails) { + // Check shutdown first (fast fail to avoid lock overhead during shutdown) + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + p.logger.Debug("tracking event ignored, provider not ready", + "event", trackingEventName) + return + } + + // Check if provider is ready + if p.Status() != of.ReadyState { + p.logger.Debug("tracking event ignored, provider not ready", + "event", trackingEventName) + return + } + + // Check context cancellation (consistent with evaluation methods) + if err := ctx.Err(); err != nil { + p.logger.Debug("tracking event ignored, context canceled", + "event", trackingEventName, + "error", err) + return + } + + // Get targeting key (user identifier) + key := evaluationContext.TargetingKey() + if key == "" { + p.logger.Warn("tracking event ignored, empty targeting key", + "event", trackingEventName, + "hint", "ensure evaluationContext has a non-empty TargetingKey") + return + } + + // Get traffic type from context attributes, default to DefaultTrafficType + // Traffic type must match a defined type in Split + trafficType := DefaultTrafficType + if attrs := evaluationContext.Attributes(); attrs != nil { + if tt, ok := attrs[TrafficTypeKey].(string); ok && tt != "" { + trafficType = tt + } + } + + // Get track options from context to check if metric value should be sent + trackOpts := GetTrackOptions(ctx) + + // Determine value to send - use nil if MetricValueAbsent to avoid polluting sum/avg metrics + var value interface{} + if trackOpts.MetricValueAbsent { + // Explicitly pass nil - Split excludes nil from sum/average calculations + // but includes 0 in sum/average calculations + value = nil + } else { + value = details.Value() + } + + // Convert OpenFeature tracking attributes to Split properties + var properties map[string]interface{} + attrs := details.Attributes() + if len(attrs) > 0 { + properties = make(map[string]interface{}, len(attrs)) + for k, v := range attrs { + properties[k] = v + } + } + + // Acquire read lock for client access to prevent concurrent shutdown + // This prevents client.Destroy() from being called during Track + p.mtx.RLock() + defer p.mtx.RUnlock() + + // Double-check shutdown after acquiring lock to prevent nil pointer dereference + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + p.logger.Debug("tracking event ignored, provider shutting down", + "event", trackingEventName) + return + } + + // Call Split SDK's Track method + if err := p.client.Track(key, trafficType, trackingEventName, value, properties); err != nil { + p.logger.Error("tracking event failed", + "event", trackingEventName, + "key", key, + "traffic_type", trafficType, + "error", err) + return + } + + p.logger.Debug("tracking event sent", + "event", trackingEventName, + "key", key, + "traffic_type", trafficType, + "value", value, + "value_omitted", trackOpts.MetricValueAbsent) +} diff --git a/evaluation_options_test.go b/evaluation_options_test.go new file mode 100644 index 0000000..eca8997 --- /dev/null +++ b/evaluation_options_test.go @@ -0,0 +1,125 @@ +package split + +import ( + "context" + "log/slog" + "strings" + "testing" + "time" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/conf" + "github.com/splitio/go-toolkit/v5/logging" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// setupLocalhostProvider creates a provider in localhost mode for direct provider-level testing. +// NOTE: This is distinct from the existing `create(t)` helper which returns +// *openfeature.Client for high-level OpenFeature API testing. This helper returns *Provider +// directly, needed for testing ObjectEvaluation, Track, and other provider methods with context options. +// Additional options (e.g. WithLogger) can be passed and are applied during construction, +// before InitWithContext, to avoid data races with background goroutines. +func setupLocalhostProvider(t *testing.T, opts ...Option) *Provider { + t.Helper() + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + allOpts := append([]Option{WithSplitConfig(cfg)}, opts...) + provider, err := New("localhost", allOpts...) + require.NoError(t, err) + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + t.Cleanup(func() { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + _ = provider.ShutdownWithContext(ctx) + }) + return provider +} + +// testProviderEvalCtx is the standard flattened evaluation context for direct provider method tests. +var testProviderEvalCtx = openfeature.FlattenedContext{ + openfeature.TargetingKey: "key", +} + +func TestObjectEvaluation_ModeIndividual_Localhost(t *testing.T) { + provider := setupLocalhostProvider(t) + + // EvaluationModeIndividual should work in localhost (it's the default) + ctx := WithEvaluationMode(context.Background(), EvaluationModeIndividual) + + result := provider.ObjectEvaluation(ctx, flagObj, nil, testProviderEvalCtx) + + flagSet, ok := result.Value.(FlagSetResult) + require.True(t, ok, "Result should be FlagSetResult") + assert.Len(t, flagSet, 1) + assert.Contains(t, flagSet, flagObj) +} + +func TestObjectEvaluation_ModeSet_IgnoredInLocalhost(t *testing.T) { + provider := setupLocalhostProvider(t) + + // Request set mode, but localhost should ignore it and use individual + ctx := WithEvaluationMode(context.Background(), EvaluationModeSet) + + result := provider.ObjectEvaluation(ctx, flagObj, nil, testProviderEvalCtx) + + // Should still evaluate single flag (localhost ignores EvaluationModeSet) + flagSet, ok := result.Value.(FlagSetResult) + require.True(t, ok, "Result should be FlagSetResult") + assert.Len(t, flagSet, 1) +} + +func TestObjectEvaluation_DefaultMode_Localhost(t *testing.T) { + provider := setupLocalhostProvider(t) + + // Default mode in localhost should use individual + result := provider.ObjectEvaluation(context.Background(), flagObj, nil, testProviderEvalCtx) + + flagSet, ok := result.Value.(FlagSetResult) + require.True(t, ok, "Result should be FlagSetResult") + assert.Len(t, flagSet, 1) + assert.Contains(t, flagSet, flagObj) +} + +func TestObjectEvaluation_LocalhostIgnoresSetMode_WithLogging(t *testing.T) { + var logBuffer strings.Builder + customLogger := slog.New(slog.NewTextHandler(&logBuffer, &slog.HandlerOptions{Level: slog.LevelDebug})) + provider := setupLocalhostProvider(t, WithLogger(customLogger)) + + // Explicitly request set mode + ctx := WithEvaluationMode(context.Background(), EvaluationModeSet) + + // Localhost should IGNORE the set mode and use individual + result := provider.ObjectEvaluation(ctx, flagObj, nil, testProviderEvalCtx) + + flagSet, ok := result.Value.(FlagSetResult) + require.True(t, ok, "Result should be FlagSetResult") + assert.Len(t, flagSet, 1) + + // Verify debug log was emitted about mode override + assert.Contains(t, logBuffer.String(), "EvaluationModeSet ignored in localhost mode") +} + +func TestImpressionDisabled_LoggedForObjectEvaluation(t *testing.T) { + var logBuffer strings.Builder + customLogger := slog.New(slog.NewTextHandler(&logBuffer, &slog.HandlerOptions{Level: slog.LevelInfo})) + provider := setupLocalhostProvider(t, WithLogger(customLogger)) + + // Set ImpressionDisabled + ctx := WithImpressionDisabled(context.Background()) + + // Should log "not yet supported" but continue evaluation + result := provider.ObjectEvaluation(ctx, flagObj, nil, testProviderEvalCtx) + + // Evaluation should still succeed + assert.NotNil(t, result.Value) + + // Verify "not yet supported" was logged (only once) + assert.Contains(t, logBuffer.String(), "not yet supported by Split Go SDK") +} diff --git a/evaluation_test.go b/evaluation_test.go new file mode 100644 index 0000000..2049a29 --- /dev/null +++ b/evaluation_test.go @@ -0,0 +1,959 @@ +//nolint:dupl,gocognit // Test patterns: type-specific tests have similar structure, comprehensive tests have higher complexity +package split + +import ( + "context" + "testing" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/conf" + "github.com/splitio/go-toolkit/v5/logging" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestEvaluationReturnsDefaultValueWhenFlagNotFound(t *testing.T) { + ofClient := create(t) + flagName := flagNonExistent + evalCtx := evaluationContext() + + // Test with default value false + result, err := ofClient.BooleanValue(context.TODO(), flagName, false, evalCtx) + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.False(t, result, "Should return default value (false)") + + // Test with default value true + result, err = ofClient.BooleanValue(context.TODO(), flagName, true, evalCtx) + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.True(t, result, "Should return default value (true)") +} + +func TestMissingTargetingKey(t *testing.T) { + ofClient := create(t) + flagName := flagNonExistent + + result, err := ofClient.BooleanValue(context.TODO(), flagName, false, openfeature.NewEvaluationContext("", nil)) + assert.Error(t, err, "Should return error when targeting key is missing") + assert.Contains(t, err.Error(), string(openfeature.TargetingKeyMissingCode), "Error should be TargetingKeyMissingCode") + assert.False(t, result, "Should return default value (false)") +} + +func TestBooleanEvaluationReturnsControlVariantForNonExistentFlag(t *testing.T) { + ofClient := create(t) + flagName := "random-non-existent-feature" + evalCtx := evaluationContext() + + result, err := ofClient.BooleanValueDetails(context.TODO(), flagName, false, evalCtx) + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.False(t, result.Value, "Should return default value (false)") + assert.Equal(t, "control", result.Variant, "Variant should be 'control' for non-existent flag") +} + +func TestBooleanEvaluationReturnsCorrectValue(t *testing.T) { + ofClient := create(t) + flagName := flagSomeOther + evalCtx := evaluationContext() + + result, err := ofClient.BooleanValue(context.TODO(), flagName, true, evalCtx) + assert.NoError(t, err, "Should not return error for valid flag") + assert.False(t, result, "Should return false for 'some_other_feature'") +} + +func TestBooleanEvaluationWithTargetingKey(t *testing.T) { + ofClient := create(t) + flagName := flagMyFeature + evalCtx := evaluationContext() + + // Test with targeting key "key" - should return true + result, err := ofClient.BooleanValue(context.TODO(), flagName, false, evalCtx) + assert.NoError(t, err, "Should not return error for valid flag") + assert.True(t, result, "Should return true for 'my_feature' with key='key'") + + // Test with different targeting key - should return false + evalCtx = openfeature.NewEvaluationContext("randomKey", nil) + result, err = ofClient.BooleanValue(context.TODO(), flagName, true, evalCtx) + assert.NoError(t, err, "Should not return error for valid flag") + assert.False(t, result, "Should return false for 'my_feature' with key='randomKey'") +} + +func TestStringEvaluationReturnsCorrectValue(t *testing.T) { + ofClient := create(t) + flagName := flagSomeOther + evalCtx := evaluationContext() + + result, err := ofClient.StringValue(context.TODO(), flagName, "on", evalCtx) + assert.NoError(t, err, "Should not return error for valid flag") + assert.Equal(t, treatmentOff, result, "Should return 'off' treatment") +} + +func TestIntEvaluationReturnsCorrectValue(t *testing.T) { + ofClient := create(t) + flagName := flagInt + evalCtx := evaluationContext() + + result, err := ofClient.IntValue(context.TODO(), flagName, 0, evalCtx) + assert.NoError(t, err, "Should not return error for valid flag") + assert.Equal(t, int64(32), result, "Should return 32") +} + +func TestObjectEvaluationReturnsCorrectValue(t *testing.T) { + ofClient := create(t) + flagName := flagObj + evalCtx := evaluationContext() + + result, err := ofClient.ObjectValue(context.TODO(), flagName, FlagSetResult{}, evalCtx) + assert.NoError(t, err, "Should not return error for valid flag") + + flags, ok := result.(FlagSetResult) + require.True(t, ok, "Result should be FlagSetResult") + require.Contains(t, flags, "obj_feature", "Should contain obj_feature flag") + + flagResult := flags["obj_feature"] + assert.Equal(t, "on", flagResult.Treatment, "Should return correct treatment") + assert.Equal(t, map[string]any{"key": "value"}, flagResult.Config, "Should return correct config") +} + +func TestFloatEvaluationReturnsCorrectValue(t *testing.T) { + ofClient := create(t) + flagName := flagInt + evalCtx := evaluationContext() + + result, err := ofClient.FloatValue(context.TODO(), flagName, 0, evalCtx) + assert.NoError(t, err, "Should not return error for valid flag") + assert.Equal(t, float64(32), result, "Should return 32.0") +} + +// ============================================================================= +// Evaluation Details Tests +// ============================================================================= + +func TestBooleanDetails(t *testing.T) { + ofClient := create(t) + flagName := flagSomeOther + evalCtx := evaluationContext() + + result, err := ofClient.BooleanValueDetails(context.TODO(), flagName, true, evalCtx) + require.NoError(t, err, "Should not return error") // Use require to prevent panic when accessing result fields + assert.Equal(t, flagName, result.FlagKey, "Flag key should match") + assert.Contains(t, string(result.Reason), string(openfeature.TargetingMatchReason), "Reason should be TargetingMatchReason") + assert.False(t, result.Value, "Value should be false") + assert.Equal(t, treatmentOff, result.Variant, "Variant should be 'off'") + assert.Empty(t, result.ErrorCode, "ErrorCode should be empty") +} + +func TestIntegerDetails(t *testing.T) { + ofClient := create(t) + flagName := flagInt + evalCtx := evaluationContext() + + result, err := ofClient.IntValueDetails(context.TODO(), flagName, 0, evalCtx) + require.NoError(t, err, "Should not return error") // Use require to prevent panic when accessing result fields + assert.Equal(t, flagName, result.FlagKey, "Flag key should match") + assert.Contains(t, string(result.Reason), string(openfeature.TargetingMatchReason), "Reason should be TargetingMatchReason") + assert.Equal(t, int64(32), result.Value, "Value should be 32") + assert.Equal(t, "32", result.Variant, "Variant should be '32'") + assert.Empty(t, result.ErrorCode, "ErrorCode should be empty") +} + +func TestStringDetails(t *testing.T) { + ofClient := create(t) + flagName := flagSomeOther + evalCtx := evaluationContext() + + result, err := ofClient.StringValueDetails(context.TODO(), flagName, "blah", evalCtx) + require.NoError(t, err, "Should not return error") // Use require to prevent panic when accessing result fields + assert.Equal(t, flagName, result.FlagKey, "Flag key should match") + assert.Contains(t, string(result.Reason), string(openfeature.TargetingMatchReason), "Reason should be TargetingMatchReason") + assert.Equal(t, treatmentOff, result.Value, "Value should be 'off'") + assert.Equal(t, treatmentOff, result.Variant, "Variant should be 'off'") + assert.Empty(t, result.ErrorCode, "ErrorCode should be empty") +} + +func TestObjectDetails(t *testing.T) { + ofClient := create(t) + flagName := flagObj + evalCtx := evaluationContext() + + result, err := ofClient.ObjectValueDetails(context.TODO(), flagName, map[string]any{}, evalCtx) + require.NoError(t, err, "Should not return error") // Use require to prevent panic when accessing result fields + assert.Equal(t, flagName, result.FlagKey, "Flag key should match") + assert.Contains(t, string(result.Reason), string(openfeature.TargetingMatchReason), "Reason should be TargetingMatchReason") + assert.Equal(t, flagName, result.Variant, "Variant should be flag name") + assert.Empty(t, result.ErrorCode, "ErrorCode should be empty") + + // Verify FlagSetResult structure + flags, ok := result.Value.(FlagSetResult) + require.True(t, ok, "Value should be FlagSetResult") + require.Contains(t, flags, "obj_feature", "Should contain obj_feature flag") + assert.Equal(t, "on", flags["obj_feature"].Treatment, "Should return correct treatment") + assert.Equal(t, map[string]any{"key": "value"}, flags["obj_feature"].Config, "Should return correct config") +} + +func TestFloatDetails(t *testing.T) { + ofClient := create(t) + flagName := flagInt + evalCtx := evaluationContext() + + result, err := ofClient.FloatValueDetails(context.TODO(), flagName, 0, evalCtx) + require.NoError(t, err, "Should not return error") // Use require to prevent panic when accessing result fields + assert.Equal(t, flagName, result.FlagKey, "Flag key should match") + assert.Contains(t, string(result.Reason), string(openfeature.TargetingMatchReason), "Reason should be TargetingMatchReason") + assert.Equal(t, float64(32), result.Value, "Value should be 32") + assert.Equal(t, "32", result.Variant, "Variant should be '32'") + assert.Empty(t, result.ErrorCode, "ErrorCode should be empty") + + // Test with actual float value + flagName = "float_feature" + result, err = ofClient.FloatValueDetails(context.TODO(), flagName, 0, evalCtx) + require.NoError(t, err, "Should not return error") + assert.Equal(t, 32.5, result.Value, "Value should be 32.5") + assert.Equal(t, "32.5", result.Variant, "Variant should be '32.5'") + assert.Empty(t, result.ErrorCode, "ErrorCode should be empty") +} + +// ============================================================================= +// Parse Error Tests +// ============================================================================= + +func TestParseErrorHandling(t *testing.T) { + ofClient := create(t) + evalCtx := evaluationContext() + + tests := []struct { + testBoolFunc func() (bool, error) + testBoolDeets func() (openfeature.BooleanEvaluationDetails, error) + testIntFunc func() (int64, error) + testIntDeets func() (openfeature.IntEvaluationDetails, error) + testFloatFunc func() (float64, error) + testFloatDeets func() (openfeature.FloatEvaluationDetails, error) + name string + intDefault int64 + floatDefault float64 + boolDefault bool + }{ + { + name: "Boolean", + testBoolFunc: func() (bool, error) { return ofClient.BooleanValue(context.TODO(), flagUnparseable, false, evalCtx) }, + testBoolDeets: func() (openfeature.BooleanEvaluationDetails, error) { + return ofClient.BooleanValueDetails(context.TODO(), flagUnparseable, false, evalCtx) + }, + boolDefault: false, + }, + { + name: "Integer", + testIntFunc: func() (int64, error) { return ofClient.IntValue(context.TODO(), flagUnparseable, 10, evalCtx) }, + testIntDeets: func() (openfeature.IntEvaluationDetails, error) { + return ofClient.IntValueDetails(context.TODO(), flagUnparseable, 10, evalCtx) + }, + intDefault: 10, + }, + { + name: "Float", + testFloatFunc: func() (float64, error) { return ofClient.FloatValue(context.TODO(), flagUnparseable, 10, evalCtx) }, + testFloatDeets: func() (openfeature.FloatEvaluationDetails, error) { + return ofClient.FloatValueDetails(context.TODO(), flagUnparseable, 10, evalCtx) + }, + floatDefault: 10.0, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // Test Value functions (Boolean, Int, Float) + if tt.testBoolFunc != nil { + result, err := tt.testBoolFunc() + require.Error(t, err, "Should return parse error") + assert.Contains(t, err.Error(), string(openfeature.ParseErrorCode), "Error should be ParseErrorCode") + assert.Equal(t, tt.boolDefault, result, "Should return default value") + + // Test Details function + details, err := tt.testBoolDeets() + require.Error(t, err, "Should return parse error") + assert.Contains(t, err.Error(), string(openfeature.ParseErrorCode), "Error should be ParseErrorCode") + assert.Equal(t, tt.boolDefault, details.Value, "Value should be default") + assert.Equal(t, openfeature.ParseErrorCode, details.ErrorCode, "ErrorCode should be ParseErrorCode") + assert.Equal(t, openfeature.ErrorReason, details.Reason, "Reason should be ErrorReason") + assert.Equal(t, treatmentUnparseable, details.Variant, "Variant should be the treatment string") + } + + if tt.testIntFunc != nil { + result, err := tt.testIntFunc() + require.Error(t, err, "Should return parse error") + assert.Contains(t, err.Error(), string(openfeature.ParseErrorCode), "Error should be ParseErrorCode") + assert.Equal(t, tt.intDefault, result, "Should return default value") + + // Test Details function + details, err := tt.testIntDeets() + require.Error(t, err, "Should return parse error") + assert.Contains(t, err.Error(), string(openfeature.ParseErrorCode), "Error should be ParseErrorCode") + assert.Equal(t, tt.intDefault, details.Value, "Value should be default") + assert.Equal(t, openfeature.ParseErrorCode, details.ErrorCode, "ErrorCode should be ParseErrorCode") + assert.Equal(t, openfeature.ErrorReason, details.Reason, "Reason should be ErrorReason") + assert.Equal(t, treatmentUnparseable, details.Variant, "Variant should be the treatment string") + } + + if tt.testFloatFunc != nil { + result, err := tt.testFloatFunc() + require.Error(t, err, "Should return parse error") + assert.Contains(t, err.Error(), string(openfeature.ParseErrorCode), "Error should be ParseErrorCode") + assert.Equal(t, tt.floatDefault, result, "Should return default value") + + // Test Details function + details, err := tt.testFloatDeets() + require.Error(t, err, "Should return parse error") + assert.Contains(t, err.Error(), string(openfeature.ParseErrorCode), "Error should be ParseErrorCode") + assert.Equal(t, tt.floatDefault, details.Value, "Value should be default") + assert.Equal(t, openfeature.ParseErrorCode, details.ErrorCode, "ErrorCode should be ParseErrorCode") + assert.Equal(t, openfeature.ErrorReason, details.Reason, "Reason should be ErrorReason") + assert.Equal(t, treatmentUnparseable, details.Variant, "Variant should be the treatment string") + } + }) + } +} + +// ============================================================================= +// Attributes and Configuration Tests +// ============================================================================= + +// TestAttributesPassedToSplit verifies that attributes from the evaluation context +// are passed to the Split SDK for targeting rules (Bug #2 fix). +func TestAttributesPassedToSplit(t *testing.T) { + ofClient := create(t) + + evalCtx := openfeature.NewEvaluationContext("key", map[string]any{ + "email": "user@example.com", + "age": int64(30), + "beta_user": true, + "account_type": "premium", + "roles": []string{"admin", "user"}, + }) + + // Test boolean evaluation with attributes + flagName := flagMyFeature + result, err := ofClient.BooleanValue(context.TODO(), flagName, false, evalCtx) + require.NoError(t, err, "Attributes should not cause error in BooleanValue") + assert.True(t, result, "Should return true for my_feature") + + // Test string evaluation with attributes + flagName2 := "some_other_feature" + strResult, err := ofClient.StringValue(context.TODO(), flagName2, "default", evalCtx) + require.NoError(t, err, "Attributes should not cause error in StringValue") + assert.Equal(t, treatmentOff, strResult, "Should return 'off' treatment") + + // Test that attributes don't interfere with existing functionality + evalCtxNoAttrs := openfeature.NewEvaluationContext("key", nil) + result2, err := ofClient.BooleanValue(context.TODO(), flagName, false, evalCtxNoAttrs) + require.NoError(t, err, "Evaluation without attributes should succeed") + assert.True(t, result2, "Should return true even without attributes") +} + +// TestDynamicConfiguration verifies that ObjectEvaluation correctly retrieves +// Dynamic Configuration from the config field. +func TestDynamicConfiguration(t *testing.T) { + ofClient := create(t) + flagName := flagMyFeature + evalCtx := openfeature.NewEvaluationContext("key", nil) + + result, err := ofClient.ObjectValue(context.TODO(), flagName, FlagSetResult{}, evalCtx) + require.NoError(t, err, "Dynamic Configuration evaluation should succeed") + + flags, ok := result.(FlagSetResult) + require.True(t, ok, "Result should be FlagSetResult") + require.Contains(t, flags, "my_feature", "Should contain my_feature flag") + + flagResult := flags["my_feature"] + assert.Equal(t, "on", flagResult.Treatment, "Should return correct treatment") + assert.Equal(t, map[string]any{"desc": "this applies only to ON treatment"}, flagResult.Config, "Should return parsed config") +} + +// TestMalformedJSONInDynamicConfiguration verifies that malformed JSON in Dynamic Configuration +// is handled gracefully - config is set to nil and a warning is logged. +func TestMalformedJSONInDynamicConfiguration(t *testing.T) { + ofClient := create(t) + evalCtx := openfeature.NewEvaluationContext("key", nil) + + t.Run("StringEvaluation", func(t *testing.T) { + details, err := ofClient.StringValueDetails(context.TODO(), flagMalformedJSON, "default", evalCtx) + require.NoError(t, err, "Should not return error for valid flag") + assert.Equal(t, treatmentOn, details.Value, "Should return treatment") + assert.Empty(t, details.FlagMetadata, "FlagMetadata should be empty for malformed JSON") + }) + + t.Run("BooleanEvaluation", func(t *testing.T) { + details, err := ofClient.BooleanValueDetails(context.TODO(), flagMalformedJSON, false, evalCtx) + require.NoError(t, err, "Should not return error for valid flag") + assert.True(t, details.Value, "Should return true for 'on' treatment") + assert.Empty(t, details.FlagMetadata, "FlagMetadata should be empty for malformed JSON") + }) + + t.Run("ObjectEvaluation", func(t *testing.T) { + result, err := ofClient.ObjectValue(context.TODO(), flagMalformedJSON, FlagSetResult{}, evalCtx) + require.NoError(t, err, "Should not return error for valid flag") + + flags, ok := result.(FlagSetResult) + require.True(t, ok, "Result should be FlagSetResult") + flagResult, ok := flags[flagMalformedJSON] + require.True(t, ok, "Result should contain flag entry") + assert.Equal(t, treatmentOn, flagResult.Treatment, "Should return treatment") + assert.Nil(t, flagResult.Config, "Config should be nil for malformed JSON") + }) +} + +// ============================================================================= +// Missing Key and Not Found Tests +// ============================================================================= + +// TestEvaluationMissingTargetingKey tests all evaluation types with missing targeting key. +func TestEvaluationMissingTargetingKey(t *testing.T) { + ofClient := create(t) + + tests := []struct { + testStrFunc func() (string, error) + testFloatFunc func() (float64, error) + testIntFunc func() (int64, error) + testObjFunc func() (any, error) + objDefault any + name string + strDefault string + floatDefault float64 + intDefault int64 + }{ + { + name: "String", + testStrFunc: func() (string, error) { + return ofClient.StringValue(context.TODO(), "str_feature", "default", openfeature.NewEvaluationContext("", nil)) + }, + strDefault: "default", + }, + { + name: "Float", + testFloatFunc: func() (float64, error) { + return ofClient.FloatValue(context.TODO(), "float_feature", 3.14, openfeature.NewEvaluationContext("", nil)) + }, + floatDefault: 3.14, + }, + { + name: "Integer", + testIntFunc: func() (int64, error) { + return ofClient.IntValue(context.TODO(), flagInt, 42, openfeature.NewEvaluationContext("", nil)) + }, + intDefault: 42, + }, + { + name: "Object", + testObjFunc: func() (any, error) { + return ofClient.ObjectValue(context.TODO(), flagObj, FlagSetResult{}, openfeature.NewEvaluationContext("", nil)) + }, + objDefault: FlagSetResult{}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if tt.testStrFunc != nil { + result, err := tt.testStrFunc() + assert.Error(t, err, "Should return error when targeting key is missing") + assert.Contains(t, err.Error(), string(openfeature.TargetingKeyMissingCode), "Error should be TargetingKeyMissingCode") + assert.Equal(t, tt.strDefault, result, "Should return default value") + } + + if tt.testFloatFunc != nil { + result, err := tt.testFloatFunc() + assert.Error(t, err, "Should return error when targeting key is missing") + assert.Contains(t, err.Error(), string(openfeature.TargetingKeyMissingCode), "Error should be TargetingKeyMissingCode") + assert.Equal(t, tt.floatDefault, result, "Should return default value") + } + + if tt.testIntFunc != nil { + result, err := tt.testIntFunc() + assert.Error(t, err, "Should return error when targeting key is missing") + assert.Contains(t, err.Error(), string(openfeature.TargetingKeyMissingCode), "Error should be TargetingKeyMissingCode") + assert.Equal(t, tt.intDefault, result, "Should return default value") + } + + if tt.testObjFunc != nil { + result, err := tt.testObjFunc() + assert.Error(t, err, "Should return error when targeting key is missing") + assert.Contains(t, err.Error(), string(openfeature.TargetingKeyMissingCode), "Error should be TargetingKeyMissingCode") + assert.Equal(t, tt.objDefault, result, "Should return default value") + } + }) + } +} + +// TestEvaluationNotFound tests all evaluation types with non-existent flags. +func TestEvaluationNotFound(t *testing.T) { + ofClient := create(t) + evalCtx := evaluationContext() + + tests := []struct { + testStrFunc func() (string, error) + testFloatFunc func() (float64, error) + testIntFunc func() (int64, error) + testObjFunc func() (any, error) + objDefault any + name string + strDefault string + floatDefault float64 + intDefault int64 + }{ + { + name: "String", + testStrFunc: func() (string, error) { + return ofClient.StringValue(context.TODO(), "nonexistent-string-feature", "default", evalCtx) + }, + strDefault: "default", + }, + { + name: "Float", + testFloatFunc: func() (float64, error) { + return ofClient.FloatValue(context.TODO(), "nonexistent-float-feature", 3.14, evalCtx) + }, + floatDefault: 3.14, + }, + { + name: "Integer", + testIntFunc: func() (int64, error) { + return ofClient.IntValue(context.TODO(), "nonexistent-int-feature", 42, evalCtx) + }, + intDefault: 42, + }, + { + name: "Object", + testObjFunc: func() (any, error) { + return ofClient.ObjectValue(context.TODO(), "nonexistent-obj-feature", FlagSetResult{}, evalCtx) + }, + objDefault: FlagSetResult{}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if tt.testStrFunc != nil { + result, err := tt.testStrFunc() + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.Equal(t, tt.strDefault, result, "Should return default value") + } + + if tt.testFloatFunc != nil { + result, err := tt.testFloatFunc() + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.Equal(t, tt.floatDefault, result, "Should return default value") + } + + if tt.testIntFunc != nil { + result, err := tt.testIntFunc() + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.Equal(t, tt.intDefault, result, "Should return default value") + } + + if tt.testObjFunc != nil { + result, err := tt.testObjFunc() + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.Equal(t, tt.objDefault, result, "Should return default value") + } + }) + } +} + +// ============================================================================= +// Edge Case Tests +// ============================================================================= + +// TestIntegerEdgeCases tests integer evaluation with boundary values and edge cases. +func TestIntegerEdgeCases(t *testing.T) { + ofClient := create(t) + evalCtx := evaluationContext() + + tests := []struct { + name string + description string + defaultValue int64 + }{ + {name: "Zero", defaultValue: 0, description: "Test with zero value"}, + {name: "Negative", defaultValue: -42, description: "Test with negative integer"}, + {name: "MaxInt64", defaultValue: 9223372036854775807, description: "Test with max int64 value"}, + {name: "MinInt64", defaultValue: -9223372036854775808, description: "Test with min int64 value"}, + {name: "SmallNegative", defaultValue: -1, description: "Test with -1 value"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result, err := ofClient.IntValue(context.TODO(), "nonexistent-int-edge-case", tt.defaultValue, evalCtx) + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.Equal(t, tt.defaultValue, result, "Should return default value: %s", tt.description) + }) + } +} + +// TestFloatEdgeCases tests float evaluation with boundary values and edge cases. +func TestFloatEdgeCases(t *testing.T) { + ofClient := create(t) + evalCtx := evaluationContext() + + tests := []struct { + name string + description string + defaultValue float64 + }{ + {name: "Zero", defaultValue: 0.0, description: "Test with zero value"}, + {name: "Negative", defaultValue: -3.14, description: "Test with negative float"}, + {name: "VerySmall", defaultValue: 1e-10, description: "Test with very small number (scientific notation)"}, + {name: "VeryLarge", defaultValue: 1e10, description: "Test with very large number"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result, err := ofClient.FloatValue(context.TODO(), "nonexistent-float-edge-case", tt.defaultValue, evalCtx) + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.Equal(t, tt.defaultValue, result, "Should return default value: %s", tt.description) + }) + } +} + +// TestStringEdgeCases tests string evaluation with edge case values. +func TestStringEdgeCases(t *testing.T) { + ofClient := create(t) + evalCtx := evaluationContext() + + tests := []struct { + name string + flagName string + defaultValue string + description string + }{ + {name: "EmptyString", flagName: "nonexistent-flag", defaultValue: "", description: "Test with empty string as default value"}, + {name: "VeryLongString", flagName: "nonexistent-flag", defaultValue: string(make([]byte, 1000)), description: "Test with very long default value (1000+ chars)"}, + {name: "UnicodeChars", flagName: "nonexistent-flag", defaultValue: "hello-世界-🌍", description: "Test with unicode characters"}, + {name: "SpecialChars", flagName: "nonexistent-flag", defaultValue: "!@#$%^&*()_+-=[]{}|;:',.<>?/~`", description: "Test with special characters"}, + {name: "Whitespace", flagName: "nonexistent-flag", defaultValue: " \t\n\r ", description: "Test with whitespace characters"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result, err := ofClient.StringValue(context.TODO(), tt.flagName, tt.defaultValue, evalCtx) + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.Equal(t, tt.defaultValue, result, "Should return default value: %s", tt.description) + }) + } +} + +// TestObjectEdgeCases tests object evaluation with edge case structures. +func TestObjectEdgeCases(t *testing.T) { + ofClient := create(t) + evalCtx := evaluationContext() + + tests := []struct { + name string + defaultValue map[string]any + description string + }{ + {name: "EmptyObject", defaultValue: map[string]any{}, description: "Test with empty object"}, + { + name: "NestedObject", + defaultValue: map[string]any{ + "level1": map[string]any{ + "level2": map[string]any{"level3": "deep"}, + }, + }, + description: "Test with deeply nested object", + }, + { + name: "ObjectWithArray", + defaultValue: map[string]any{ + "items": []any{"a", "b", "c"}, + "counts": []int{1, 2, 3}, + }, + description: "Test with arrays in object", + }, + { + name: "ObjectWithNull", + defaultValue: map[string]any{"key": "value", "nullField": nil}, + description: "Test with null values in object", + }, + { + name: "MixedTypes", + defaultValue: map[string]any{ + "string": "text", "number": 42, "float": 3.14, "bool": true, + "array": []any{1, "two", 3.0}, "nested": map[string]any{"inner": "value"}, + }, + description: "Test with mixed types in object", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result, err := ofClient.ObjectValue(context.TODO(), "nonexistent-obj-edge-case", tt.defaultValue, evalCtx) + assert.Error(t, err, "Should return error for non-existent flag") + assert.Contains(t, err.Error(), string(openfeature.FlagNotFoundCode), "Error should be FlagNotFoundCode") + assert.Equal(t, tt.defaultValue, result, "Should return default value: %s", tt.description) + }) + } +} + +// TestTargetingKeyEdgeCases tests various edge cases for targeting keys. +func TestTargetingKeyEdgeCases(t *testing.T) { + ofClient := create(t) + + tests := []struct { + name string + targetingKey string + flagName string + description string + }{ + {name: "EmptyTargetingKey", targetingKey: "", flagName: flagSomeOther, description: "Test with empty targeting key"}, + {name: "VeryLongTargetingKey", targetingKey: string(make([]byte, 1000)), flagName: flagSomeOther, description: "Test with very long targeting key (1000+ chars)"}, + {name: "UnicodeTargetingKey", targetingKey: "user-世界-🌍", flagName: flagSomeOther, description: "Test with unicode in targeting key"}, + {name: "SpecialCharsTargetingKey", targetingKey: "user@example.com", flagName: flagSomeOther, description: "Test with email-like targeting key"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + evalCtx := openfeature.NewEvaluationContext(tt.targetingKey, nil) + + result, err := ofClient.BooleanValue(context.TODO(), tt.flagName, true, evalCtx) + + if tt.targetingKey == "" { + assert.Error(t, err, "Should return error for empty targeting key") + assert.Contains(t, err.Error(), string(openfeature.TargetingKeyMissingCode), "Error should be TargetingKeyMissingCode") + } else { + _ = result + _ = err + } + }) + } +} + +// ============================================================================= +// Context Cancellation Tests +// ============================================================================= + +// TestContextCancellation verifies that canceled contexts are respected in all evaluation methods. +func TestContextCancellation(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + // Create a canceled context + ctx, cancel := context.WithCancel(context.Background()) + cancel() // Cancel immediately + + flatCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: "test-user", + } + + // Test Boolean evaluation with canceled context + boolResult := provider.BooleanEvaluation(ctx, flagSomeOther, true, flatCtx) + assert.Equal(t, true, boolResult.Value, "Should return default value when context is canceled") + assert.Equal(t, openfeature.ErrorReason, boolResult.Reason, "Should have error reason") + assert.NotNil(t, boolResult.ResolutionError, "Should have resolution error") + + // Test String evaluation with canceled context + strResult := provider.StringEvaluation(ctx, flagSomeOther, "default", flatCtx) + assert.Equal(t, "default", strResult.Value, "Should return default value when context is canceled") + assert.Equal(t, openfeature.ErrorReason, strResult.Reason, "Should have error reason") + assert.NotNil(t, strResult.ResolutionError, "Should have resolution error") + + // Test Int evaluation with canceled context + intResult := provider.IntEvaluation(ctx, flagInt, 999, flatCtx) + assert.Equal(t, int64(999), intResult.Value, "Should return default value when context is canceled") + assert.Equal(t, openfeature.ErrorReason, intResult.Reason, "Should have error reason") + assert.NotNil(t, intResult.ResolutionError, "Should have resolution error") + + // Test Float evaluation with canceled context + floatResult := provider.FloatEvaluation(ctx, "some_flag", 123.45, flatCtx) + assert.Equal(t, 123.45, floatResult.Value, "Should return default value when context is canceled") + assert.Equal(t, openfeature.ErrorReason, floatResult.Reason, "Should have error reason") + assert.NotNil(t, floatResult.ResolutionError, "Should have resolution error") + + // Test Object evaluation with canceled context + defaultObj := FlagSetResult{} + objResult := provider.ObjectEvaluation(ctx, "some_flag", defaultObj, flatCtx) + assert.Equal(t, defaultObj, objResult.Value, "Should return default value when context is canceled") + assert.Equal(t, openfeature.ErrorReason, objResult.Reason, "Should have error reason") + assert.NotNil(t, objResult.ResolutionError, "Should have resolution error") +} + +// ============================================================================= +// PROVIDER_NOT_READY Evaluation Tests +// ============================================================================= + +// TestEvaluationWhenProviderNotReady tests all evaluation types when provider is not initialized. +func TestEvaluationWhenProviderNotReady(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + + // Initialize then shut down to reliably put provider in NotReady state. + // We can't rely on "not calling Init" because in localhost mode, the Split SDK + // factory auto-initializes from the YAML file during New() (factory.IsReady() == true). + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + err = provider.ShutdownWithContext(context.Background()) + require.NoError(t, err) + require.Equal(t, openfeature.NotReadyState, provider.Status(), "Provider should be NotReady after shutdown") + + flatCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: "test-user", + } + + t.Run("Boolean", func(t *testing.T) { + result := provider.BooleanEvaluation(context.TODO(), flagSomeOther, true, flatCtx) + assert.Equal(t, true, result.Value, "Should return default value") + assert.Equal(t, openfeature.ErrorReason, result.Reason) + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.ProviderNotReadyCode)) + }) + + t.Run("String", func(t *testing.T) { + result := provider.StringEvaluation(context.TODO(), flagSomeOther, "default", flatCtx) + assert.Equal(t, "default", result.Value, "Should return default value") + assert.Equal(t, openfeature.ErrorReason, result.Reason) + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.ProviderNotReadyCode)) + }) + + t.Run("Int", func(t *testing.T) { + result := provider.IntEvaluation(context.TODO(), flagInt, 42, flatCtx) + assert.Equal(t, int64(42), result.Value, "Should return default value") + assert.Equal(t, openfeature.ErrorReason, result.Reason) + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.ProviderNotReadyCode)) + }) + + t.Run("Float", func(t *testing.T) { + result := provider.FloatEvaluation(context.TODO(), flagInt, 3.14, flatCtx) + assert.Equal(t, 3.14, result.Value, "Should return default value") + assert.Equal(t, openfeature.ErrorReason, result.Reason) + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.ProviderNotReadyCode)) + }) + + t.Run("Object", func(t *testing.T) { + defaultObj := FlagSetResult{} + result := provider.ObjectEvaluation(context.TODO(), flagObj, defaultObj, flatCtx) + assert.Equal(t, defaultObj, result.Value, "Should return default value") + assert.Equal(t, openfeature.ErrorReason, result.Reason) + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.ProviderNotReadyCode)) + }) +} + +// ============================================================================= +// INVALID_CONTEXT Evaluation Tests +// ============================================================================= + +// TestEvaluationWithInvalidContext tests evaluation with a non-string targeting key. +func TestEvaluationWithInvalidContext(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + // Targeting key exists but is NOT a string (integer instead) + flatCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: 12345, + } + + t.Run("Boolean", func(t *testing.T) { + result := provider.BooleanEvaluation(context.TODO(), flagSomeOther, true, flatCtx) + assert.Equal(t, true, result.Value, "Should return default value") + assert.Equal(t, openfeature.ErrorReason, result.Reason) + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.InvalidContextCode)) + }) + + t.Run("String", func(t *testing.T) { + result := provider.StringEvaluation(context.TODO(), flagSomeOther, "default", flatCtx) + assert.Equal(t, "default", result.Value, "Should return default value") + assert.Equal(t, openfeature.ErrorReason, result.Reason) + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.InvalidContextCode)) + }) + + t.Run("Int", func(t *testing.T) { + result := provider.IntEvaluation(context.TODO(), flagInt, 42, flatCtx) + assert.Equal(t, int64(42), result.Value, "Should return default value") + assert.Equal(t, openfeature.ErrorReason, result.Reason) + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.InvalidContextCode)) + }) + + t.Run("Float", func(t *testing.T) { + result := provider.FloatEvaluation(context.TODO(), flagInt, 3.14, flatCtx) + assert.Equal(t, 3.14, result.Value, "Should return default value") + assert.Equal(t, openfeature.ErrorReason, result.Reason) + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.InvalidContextCode)) + }) + + t.Run("Object", func(t *testing.T) { + defaultObj := FlagSetResult{} + result := provider.ObjectEvaluation(context.TODO(), flagObj, defaultObj, flatCtx) + assert.Equal(t, defaultObj, result.Value, "Should return default value") + assert.Equal(t, openfeature.ErrorReason, result.Reason) + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.InvalidContextCode)) + }) +} + +// ============================================================================= +// Integration Tests +// ============================================================================= + +// TestIntegrationWithOpenFeatureSDK tests integration with the OpenFeature SDK. +func TestIntegrationWithOpenFeatureSDK(t *testing.T) { + if testing.Short() { + t.Skip("Skipping integration test in short mode") + } + + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + flatCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: "test-user", + } + + // Test boolean evaluation + boolResult := provider.BooleanEvaluation(context.TODO(), flagSomeOther, false, flatCtx) + assert.Equal(t, openfeature.TargetingMatchReason, boolResult.Reason, "Boolean evaluation should succeed") + assert.False(t, boolResult.Value, "Boolean value should be false for flagSomeOther") + + // Test string evaluation + strResult := provider.StringEvaluation(context.TODO(), flagSomeOther, "default", flatCtx) + assert.Equal(t, openfeature.TargetingMatchReason, strResult.Reason, "String evaluation should succeed") + assert.Equal(t, treatmentOff, strResult.Value, "String value should be 'off'") + + // Test integer evaluation + intResult := provider.IntEvaluation(context.TODO(), flagInt, 0, flatCtx) + assert.Equal(t, openfeature.TargetingMatchReason, intResult.Reason, "Int evaluation should succeed") + assert.Equal(t, int64(32), intResult.Value, "Int value should be 32") +} diff --git a/events.go b/events.go new file mode 100644 index 0000000..a5c5a63 --- /dev/null +++ b/events.go @@ -0,0 +1,220 @@ +package split + +import ( + "fmt" + "sync/atomic" + "time" + + of "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/client" +) + +// EventChannel returns a channel for receiving provider lifecycle events. +// +// This method implements the EventHandler interface. The OpenFeature SDK +// uses this channel to receive events about provider state changes. +// +// Events Emitted: +// - PROVIDER_READY: Provider initialized successfully +// - PROVIDER_ERROR: Provider encountered initialization error +// - PROVIDER_CONFIGURATION_CHANGED: Split definitions updated (detected via polling) +// +// Configuration Change Detection Limitation: +// PROVIDER_CONFIGURATION_CHANGED is detected by polling, not via real-time SSE streaming. +// While the Split SDK receives changes instantly via SSE, it doesn't expose a callback +// for configuration changes. The provider polls manager.Splits() and compares ChangeNumber +// values to detect changes. The polling interval is configurable via WithMonitoringInterval +// (default: 30 seconds, minimum: 5 seconds). +// +// Staleness Detection Limitation: +// PROVIDER_STALE events are NOT currently emitted. The Split SDK's IsReady() +// method only indicates initial readiness and does not change when network +// connectivity is lost during operation. The SDK handles connectivity issues +// internally (switching between streaming and polling modes) but does not +// expose this state through its public API. +// +// When network connectivity is lost, the SDK continues serving cached data +// silently. Applications requiring staleness awareness should implement +// application-level health checks or monitor SDK debug logs. +// +// See CONTRIBUTING.md for details on this known limitation and potential +// future enhancements if Split SDK exposes streaming/connectivity status. +// +// The channel is buffered (128 events) to prevent blocking event emission. +// Applications can register handlers via openfeature.AddHandler() to react to events. +// +// Example: +// +// openfeature.AddHandler(openfeature.ProviderReady, func(details openfeature.EventDetails) { +// log.Println("Split provider is ready!") +// }) +// +// openfeature.AddHandler(openfeature.ProviderConfigChange, func(details openfeature.EventDetails) { +// log.Println("Feature flags updated - may want to re-evaluate") +// }) +func (p *Provider) EventChannel() <-chan of.Event { + return p.eventStream +} + +// emitEvent sends an event to the event channel without blocking. +// +// If the channel buffer is full, the event is dropped and a warning is logged. +// This prevents slow event consumers from blocking provider operations. +// If the provider is shut down and the channel is closed, the send is silently ignored. +// +// Concurrency Safety Design: +// Uses atomic shutdown check as a fast path, then acquires a brief read lock +// for the actual channel send. This prevents race detector warnings while +// keeping the lock duration minimal (just the non-blocking select). +func (p *Provider) emitEvent(event *of.Event) { + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + return + } + + // Acquire read lock for channel send to prevent race with close() + // The lock duration is minimal - just the non-blocking select + p.mtx.RLock() + defer p.mtx.RUnlock() + + // Double-check shutdown after acquiring lock + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + return + } + + select { + case p.eventStream <- *event: + default: + p.logger.Warn("event channel full, dropping event", "event_type", event.EventType) + } +} + +// monitorSplitUpdates runs in a background goroutine to monitor Split SDK updates. +// +// This goroutine: +// - Polls the Split SDK for changes in split definitions +// - Emits PROVIDER_CONFIGURATION_CHANGED events when splits are updated +// - Gracefully shuts down when stopMonitor channel is closed +// +// The monitoring interval is configurable via WithMonitoringInterval (default: 30s, min: 5s). +// +// Panic Recovery: +// If a panic occurs (e.g., nil pointer in SDK), the goroutine recovers, logs the error, +// and terminates gracefully. This prevents the monitoring goroutine from leaving +// monitorDone unclosed, which would cause shutdown to hang. +func (p *Provider) monitorSplitUpdates() { + defer func() { + if r := recover(); r != nil { + p.logger.Error("monitoring goroutine panicked, terminating gracefully", + "panic", r, + "advice", "this may indicate a bug in Split SDK or provider implementation") + p.emitEvent(&of.Event{ + ProviderName: p.Metadata().Name, + EventType: of.ProviderError, + ProviderEventDetails: of.ProviderEventDetails{ + Message: fmt.Sprintf("monitoring goroutine panicked: %v", r), + }, + }) + } + close(p.monitorDone) + p.logger.Debug("monitoring goroutine stopped") + }() + + manager, lastKnownSplits, ok := p.initMonitorState() + if !ok { + p.emitEvent(&of.Event{ + ProviderName: p.Metadata().Name, + EventType: of.ProviderError, + ProviderEventDetails: of.ProviderEventDetails{ + Message: "monitoring failed to start: factory or manager unavailable", + }, + }) + return + } + + p.logger.Debug("starting background Split monitoring", + "interval", p.monitoringInterval, + "initial_splits", len(lastKnownSplits)) + + ticker := time.NewTicker(p.monitoringInterval) + defer ticker.Stop() + + for { + select { + case <-p.stopMonitor: + p.logger.Debug("received shutdown signal, stopping monitoring") + return + + case <-ticker.C: + currentSplits := p.pollCurrentSplits(manager) + if splitsChanged(lastKnownSplits, currentSplits) { + p.logger.Debug("Split definitions changed", + "old_count", len(lastKnownSplits), + "new_count", len(currentSplits)) + p.emitEvent(&of.Event{ + ProviderName: p.Metadata().Name, + EventType: of.ProviderConfigChange, + ProviderEventDetails: of.ProviderEventDetails{ + Message: fmt.Sprintf("Split definitions updated (count: %d)", len(currentSplits)), + }, + }) + lastKnownSplits = currentSplits + } + } + } +} + +// initMonitorState acquires the factory/manager and captures initial split state. +// Uses defer for panic-safe RLock release — if manager.Splits() panics, the lock +// is released before the panic propagates to the outer recovery handler. +func (p *Provider) initMonitorState() (*client.SplitManager, map[string]int64, bool) { + p.mtx.RLock() + defer p.mtx.RUnlock() + + if p.factory == nil { + p.logger.Error("no factory available for monitoring despite provider reporting ready") + return nil, nil, false + } + + manager := p.factory.Manager() + if manager == nil { + p.logger.Error("factory manager is nil, stopping monitoring", + "reason", "Split SDK may not be fully initialized or factory is in invalid state") + return nil, nil, false + } + + lastKnownSplits := make(map[string]int64) + splits := manager.Splits() + for i := range splits { + lastKnownSplits[splits[i].Name] = splits[i].ChangeNumber + } + return manager, lastKnownSplits, true +} + +// pollCurrentSplits reads the current split state under RLock. +// Uses defer for panic-safe RLock release. +func (p *Provider) pollCurrentSplits(manager *client.SplitManager) map[string]int64 { + p.mtx.RLock() + defer p.mtx.RUnlock() + + currentSplits := make(map[string]int64) + currentSplitList := manager.Splits() + for i := range currentSplitList { + currentSplits[currentSplitList[i].Name] = currentSplitList[i].ChangeNumber + } + return currentSplits +} + +// splitsChanged checks if splits have changed by comparing names and change numbers. +// Returns true if any split was added, removed, or modified. +func splitsChanged(old, current map[string]int64) bool { + if len(old) != len(current) { + return true + } + for name, changeNum := range current { + oldChangeNum, exists := old[name] + if !exists || oldChangeNum != changeNum { + return true + } + } + return false +} diff --git a/examples/cloud/README.md b/examples/cloud/README.md new file mode 100644 index 0000000..4e48b4b --- /dev/null +++ b/examples/cloud/README.md @@ -0,0 +1,61 @@ +# Cloud Example + +**Cloud mode example** demonstrating Split OpenFeature Provider in streaming/cloud mode. + +## What This Demonstrates + +- Provider initialization in **streaming/cloud mode** with structured colored logging +- Boolean, String, Integer, Float, and **Object** flag evaluations +- Evaluation context with targeting keys and attributes +- Getting evaluation details (variant, reason, flag metadata) +- **Flag sets** evaluation (object evaluations in cloud mode) +- **Flag metadata** (JSON configurations attached to treatments) +- Provider health checks +- Source-attributed logs for debugging + +**Requires Split API key** - Connects to Split's cloud service for real-time flag updates via streaming. + +## Prerequisites + +Get your Split API key from [Split.io](https://split.io) (use server-side SDK key). + +## Running + +```bash +cd examples/cloud +export SPLIT_API_KEY="your-server-side-sdk-key" +go run main.go +``` + +The example will: + +1. Initialize the Split provider in cloud/streaming mode +2. Evaluate multiple flag types (boolean, string, int, float, object) +3. Demonstrate flag sets and flag metadata +4. Show evaluation details and provider health +5. Display structured colored logs with source attribution + +## Troubleshooting + +### "SPLIT_API_KEY environment variable is required" + +- Make sure you've set the environment variable: `export SPLIT_API_KEY="your-key"` +- Verify your key is correct in the UI under Admin → API Keys + +### Flags returning default values + +- This is normal if flags don't exist in Split +- Create the flags in the UI to see different behaviors +- Check that you're using the correct SDK key (server-side, not client-side) + +### Provider initialization timeout + +- Check your network connection +- Verify the API key is valid +- The SDK needs to download flag definitions on first run + +## Learn More + +- [Split OpenFeature Go Provider Documentation](../../README.md) +- [OpenFeature Go SDK](https://openfeature.dev/docs/reference/sdks/server/go) +- [Split Go SDK](https://github.com/splitio/go-client) diff --git a/examples/cloud/main.go b/examples/cloud/main.go new file mode 100644 index 0000000..a43954e --- /dev/null +++ b/examples/cloud/main.go @@ -0,0 +1,214 @@ +// Package main demonstrates cloud mode usage of the Split OpenFeature Provider. +// +// This example shows how to: +// - Create and initialize a Split provider in streaming/cloud mode +// - Evaluate different flag types (boolean, string, int, float, object) +// - Get evaluation details (variant, reason, flag metadata) +// - Monitor provider health +// +// This example requires a Split API key and connects to Split's cloud service. +// Flags that don't exist return their default values - create flags in Split dashboard. +// +// Run: SPLIT_API_KEY=your-key-here go run main.go +package main + +import ( + "context" + "log/slog" + "os" + "time" + + "github.com/lmittmann/tint" + "github.com/open-feature/go-sdk/openfeature" + "github.com/open-feature/go-sdk/openfeature/hooks" + + "github.com/splitio/split-openfeature-provider-go/v2" +) + +func main() { + logLevel := slog.LevelInfo + if level := os.Getenv("LOG_LEVEL"); level != "" { + switch level { + case "debug", "DEBUG", "trace", "TRACE": + logLevel = slog.LevelDebug + case "info", "INFO": + logLevel = slog.LevelInfo + case "warn", "WARN", "warning", "WARNING": + logLevel = slog.LevelWarn + case "error", "ERROR": + logLevel = slog.LevelError + default: + logLevel = slog.LevelInfo + slog.Warn("invalid LOG_LEVEL, using INFO", "provided", level, "valid", "debug|info|warn|error") + } + } + + baseLogger := slog.New(tint.NewHandler(os.Stderr, &tint.Options{ + Level: logLevel, + TimeFormat: time.TimeOnly, + })) + + appLogger := baseLogger.With("source", "app") + ofLogger := baseLogger.With("source", "openfeature-sdk") + + slog.SetDefault(baseLogger) + + apiKey := os.Getenv("SPLIT_API_KEY") + if apiKey == "" { + appLogger.Error("SPLIT_API_KEY environment variable is required") + os.Exit(1) + } + + // Use optimized test configuration for faster startup + cfg := split.TestConfig() + + provider, err := split.New(apiKey, + split.WithLogger(baseLogger), + split.WithSplitConfig(cfg), + ) + if err != nil { + appLogger.Error("failed to create provider", "error", err) + os.Exit(1) + } + + defer func() { + shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if err := openfeature.ShutdownWithContext(shutdownCtx); err != nil { + appLogger.Error("shutdown error", "error", err) + } + }() + + openfeature.AddHooks(hooks.NewLoggingHook(false, ofLogger)) + + initCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + + if err := openfeature.SetNamedProviderWithContextAndWait(initCtx, "cloud-streaming", provider); err != nil { + appLogger.Error("failed to initialize provider", "error", err) + os.Exit(1) + } + + appLogger.Info("Split provider initialized successfully in cloud/streaming mode") + + client := openfeature.NewClient("cloud-streaming") + ctx := context.Background() + + // Check provider state + if client.State() == openfeature.ReadyState { + appLogger.Info("provider is ready for evaluations") + } + + // Get client metadata + metadata := client.Metadata() + appLogger.Info("client metadata", "domain", metadata.Domain()) + + evalCtx := openfeature.NewEvaluationContext("user-123", map[string]any{ + "email": "user@example.com", + "plan": "premium", + }) + + // Example 1: Boolean flag evaluation + appLogger.Info("boolean flag evaluation") + showNewFeature, err := client.BooleanValue(ctx, "feature_boolean_on", false, evalCtx) + if err != nil { + appLogger.Warn("error evaluating boolean flag", "error", err) + } + appLogger.Info("flag evaluated", "flag", "feature_boolean_on", "value", showNewFeature, "default", false) + + // Example 2: String flag evaluation + appLogger.Info("string flag evaluation") + theme, err := client.StringValue(ctx, "ui_theme", "light", evalCtx) + if err != nil { + appLogger.Warn("error evaluating string flag", "error", err) + } + appLogger.Info("flag evaluated", "flag", "ui_theme", "value", theme, "default", "light") + + // Example 3: Integer flag evaluation + appLogger.Info("integer flag evaluation") + maxRetries, err := client.IntValue(ctx, "max_retries", 3, evalCtx) + if err != nil { + appLogger.Warn("error evaluating integer flag", "error", err) + } + appLogger.Info("flag evaluated", "flag", "max_retries", "value", maxRetries, "default", 3) + + // Example 4: Float flag evaluation + appLogger.Info("float flag evaluation") + discountRate, err := client.FloatValue(ctx, "discount_rate", 0.0, evalCtx) + if err != nil { + appLogger.Warn("error evaluating float flag", "error", err) + } + appLogger.Info("flag evaluated", "flag", "discount_rate", "value", discountRate, "default", 0.0) + + // Example 5: Object flag evaluation (evaluates flag sets in cloud mode) + appLogger.Info("object flag evaluation (flag set)") + flagSetData, err := client.ObjectValue(ctx, "split_provider_test", split.FlagSetResult{}, evalCtx) + if err != nil { + appLogger.Warn("error evaluating object flag", "error", err) + } else if flags, ok := flagSetData.(split.FlagSetResult); ok { + appLogger.Info("flag set evaluated", + "flag_set", "split_provider_test", + "flags_count", len(flags)) + // Access individual flags using the struct + if uiTheme, ok := flags["ui_theme"]; ok { + appLogger.Info("flag from set", "flag", "ui_theme", "treatment", uiTheme.Treatment) + } + } + + // Example 6: Get evaluation details with flag metadata + appLogger.Info("getting evaluation details with metadata") + details, err := client.StringValueDetails(ctx, "ui_theme", "light", evalCtx) + if err != nil { + appLogger.Warn("error getting evaluation details", "error", err) + } else { + appLogger.Info("evaluation details", + "value", details.Value, + "variant", details.Variant, + "reason", details.Reason, + "flag_key", details.FlagKey, + "has_metadata", len(details.FlagMetadata) > 0) + if len(details.FlagMetadata) > 0 { + appLogger.Info("flag metadata available", + "metadata_keys", len(details.FlagMetadata)) + } + } + + // Example 7: Evaluation mode - force individual flag evaluation in cloud mode + // By default, ObjectEvaluation in cloud mode evaluates flag sets. + // Use WithEvaluationMode to evaluate a single flag as an object instead. + appLogger.Info("individual flag evaluation in cloud mode") + individualCtx := split.WithEvaluationMode(ctx, split.EvaluationModeIndividual) + singleFlag, err := client.ObjectValue(individualCtx, "ui_theme", split.FlagSetResult{}, evalCtx) + if err != nil { + appLogger.Warn("error evaluating individual flag", "error", err) + } else if flags, ok := singleFlag.(split.FlagSetResult); ok { + appLogger.Info("individual flag evaluated", "flags_count", len(flags)) + } + + // Example 8: Track event with metric value + appLogger.Info("tracking events") + trackDetails := openfeature.NewTrackingEventDetails(99.99). + Add("currency", "USD") + client.Track(ctx, "purchase", evalCtx, trackDetails) + appLogger.Info("tracked event with metric value", "event", "purchase", "value", 99.99) + + // Example 9: Track count-only event (no metric value) + // Use WithoutMetricValue to avoid polluting sum/average metrics with zeros + noValueCtx := split.WithoutMetricValue(ctx) + countDetails := openfeature.NewTrackingEventDetails(0). + Add("page", "/home") + client.Track(noValueCtx, "page_view", evalCtx, countDetails) + appLogger.Info("tracked count-only event (nil value sent to Split)", "event", "page_view") + + // Example 10: Provider health check + appLogger.Info("provider health check") + metrics := provider.Metrics() + appLogger.Info("provider health", + "provider", metrics.Provider, + "status", metrics.Status, + "initialized", metrics.Initialized, + "ready", metrics.Ready, + "splits_count", metrics.SplitsCount) + + appLogger.Info("example completed successfully") +} diff --git a/examples/localhost/README.md b/examples/localhost/README.md new file mode 100644 index 0000000..65e13a0 --- /dev/null +++ b/examples/localhost/README.md @@ -0,0 +1,79 @@ +# Localhost Mode Example + +**No Split account needed!** This example demonstrates offline flag evaluation using local YAML files. + +## What This Demonstrates + +- Localhost mode configuration (no network calls to Split) +- Loading feature flags from local YAML file +- User-specific targeting with key-based routing +- All flag types (Boolean, String, Integer, Float, Object) +- Flag metadata (JSON configurations attached to treatments) +- Colored structured logging with source attribution +- Perfect for CI/CD and integration tests + +## Why Use Localhost Mode? + +Perfect for: + +- Local development without Split account +- Unit/integration testing with predictable values +- CI/CD pipelines requiring deterministic behavior +- Working offline or in restricted networks + +**WARNING:** Localhost mode does NOT sync with Split servers. Development/testing only - never use in production. + +## Running + +```bash +cd examples/localhost +go run main.go +``` + +No environment variables or API keys needed! The example will: + +1. Load flags from `split.yaml` +2. Evaluate flags for multiple users +3. Show targeting behavior +4. Display structured logs with source attribution + +## Split File Format + +The `split.yaml` file defines feature flags: + +```yaml +- flag_name: + treatment: "value" + keys: "user-1,user-2" # Optional: target specific users + config: '{"key": "value"}' # Optional: JSON configuration +``` + +## Limitations + +**Flag Sets Not Supported:** Localhost mode does NOT support flag sets for bulk evaluation. + +## Troubleshooting + +### "File not found" Error + +- Ensure `split.yaml` exists in the same directory +- Use absolute paths if needed: `cfg.SplitFile = "/path/to/split.yaml"` + +### Flags Always Return Defaults + +- Check YAML syntax (proper indentation) +- Verify flag names match exactly (case-sensitive) +- Check the `keys` field if using targeted rollouts + +### Invalid YAML Format + +- Ensure proper YAML structure +- Use quotes around string values with special characters +- Validate YAML with online tools + +## Learn More + +- [Cloud Example](../cloud/) - Cloud mode with streaming +- [Split OpenFeature Go Provider Documentation](../../README.md) +- [OpenFeature Go SDK](https://openfeature.dev/docs/reference/sdks/server/go) +- [Split Go SDK](https://github.com/splitio/go-client) diff --git a/examples/localhost/main.go b/examples/localhost/main.go new file mode 100644 index 0000000..4223168 --- /dev/null +++ b/examples/localhost/main.go @@ -0,0 +1,203 @@ +// Package main demonstrates localhost mode usage of the Split OpenFeature Provider. +// +// Localhost mode is ideal for: +// - Development and testing without Split.io account +// - Testing flag configurations locally before deployment +// - CI/CD pipelines and integration tests +// +// This example shows how to: +// - Configure Split SDK in localhost mode +// - Load flags from a local YAML file (split.yaml) +// - Evaluate flags with different user attributes +// +// Run: go run main.go +package main + +import ( + "context" + "log/slog" + "os" + "time" + + "github.com/lmittmann/tint" + "github.com/open-feature/go-sdk/openfeature" + "github.com/open-feature/go-sdk/openfeature/hooks" + + "github.com/splitio/split-openfeature-provider-go/v2" +) + +func main() { + logLevel := slog.LevelInfo + if level := os.Getenv("LOG_LEVEL"); level != "" { + switch level { + case "debug", "DEBUG", "trace", "TRACE": + logLevel = slog.LevelDebug + case "info", "INFO": + logLevel = slog.LevelInfo + case "warn", "WARN", "warning", "WARNING": + logLevel = slog.LevelWarn + case "error", "ERROR": + logLevel = slog.LevelError + default: + logLevel = slog.LevelInfo + slog.Warn("invalid LOG_LEVEL, using INFO", "provided", level, "valid", "debug|info|warn|error") + } + } + + baseLogger := slog.New(tint.NewHandler(os.Stderr, &tint.Options{ + Level: logLevel, + TimeFormat: time.TimeOnly, + })) + + appLogger := baseLogger.With("source", "app") + ofLogger := baseLogger.With("source", "openfeature-sdk") + + slog.SetDefault(baseLogger) + + appLogger.Info("Split OpenFeature Provider - localhost mode example") + appLogger.Warn("this example runs in LOCALHOST MODE for development/testing") + appLogger.Info("reading feature flags from ./split.yaml") + + // Use optimized test configuration for faster startup + cfg := split.TestConfig() + cfg.SplitFile = "./split.yaml" + + provider, err := split.New("localhost", split.WithSplitConfig(cfg), split.WithLogger(baseLogger)) + if err != nil { + appLogger.Error("failed to create provider", "error", err) + os.Exit(1) + } + + defer func() { + shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if err := openfeature.ShutdownWithContext(shutdownCtx); err != nil { + appLogger.Error("shutdown error", "error", err) + } + }() + + openfeature.AddHooks(hooks.NewLoggingHook(false, ofLogger)) + + initCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + + if err := openfeature.SetProviderWithContextAndWait(initCtx, provider); err != nil { + appLogger.Error("failed to initialize provider", "error", err) + os.Exit(1) + } + + appLogger.Info("provider initialized in localhost mode") + + // Create default OpenFeature client (uses default provider) + ofClient := openfeature.NewDefaultClient() + ctx := context.Background() + + // Check provider state + if ofClient.State() == openfeature.ReadyState { + appLogger.Info("provider is ready for evaluations") + } + + // Get client metadata + metadata := ofClient.Metadata() + appLogger.Info("client metadata", "domain", metadata.Domain()) + + // Test with different users to see targeting in action + testUsers := []string{"user-123", "user-456", "user-789"} + + for _, userID := range testUsers { + appLogger.Info("evaluating flags for user", "user_id", userID) + evalCtx := openfeature.NewEvaluationContext(userID, nil) + + // Boolean flag with targeting + newFeature, _ := ofClient.BooleanValue(ctx, "new_feature", false, evalCtx) + appLogger.Info("boolean flag evaluated", "flag", "new_feature", "value", newFeature) + + // String flag + theme, _ := ofClient.StringValue(ctx, "ui_theme", "light", evalCtx) + appLogger.Info("string flag evaluated", "flag", "ui_theme", "value", theme) + + // Integer flag + maxRetries, _ := ofClient.IntValue(ctx, "max_retries", 3, evalCtx) + appLogger.Info("integer flag evaluated", "flag", "max_retries", "value", maxRetries) + + // Float flag + discount, _ := ofClient.FloatValue(ctx, "discount_rate", 0.0, evalCtx) + appLogger.Info("float flag evaluated", "flag", "discount_rate", "value", discount) + + // Object flag with dynamic configuration - returns FlagSetResult + premiumFeatures, _ := ofClient.ObjectValue(ctx, "premium_features", split.FlagSetResult{}, evalCtx) + if flags, ok := premiumFeatures.(split.FlagSetResult); ok { + if flag, ok := flags["premium_features"]; ok { + appLogger.Info("object flag evaluated", + "flag", "premium_features", + "treatment", flag.Treatment, + "has_config", flag.Config != nil) + } + } + + // Get evaluation details to see variant/treatment + details, _ := ofClient.BooleanValueDetails(ctx, "new_feature", false, evalCtx) + appLogger.Info("flag details", "variant", details.Variant, "reason", details.Reason) + } + + // Demonstrate evaluation options + // Note: In localhost mode, EvaluationModeSet is ignored (always uses individual). + // EvaluationModeIndividual works as expected. + appLogger.Info("evaluation mode options (localhost mode)") + demoEvalCtx := openfeature.NewEvaluationContext("demo-user", nil) + individualCtx := split.WithEvaluationMode(ctx, split.EvaluationModeIndividual) + premiumIndividual, _ := ofClient.ObjectValue(individualCtx, "premium_features", split.FlagSetResult{}, demoEvalCtx) + if flags, ok := premiumIndividual.(split.FlagSetResult); ok { + appLogger.Info("individual mode evaluation", "flags_count", len(flags)) + } + + // Demonstrate track options + appLogger.Info("track options") + + // Track with metric value (purchase amount) + purchaseDetails := openfeature.NewTrackingEventDetails(149.99). + Add("currency", "USD") + ofClient.Track(ctx, "purchase", demoEvalCtx, purchaseDetails) + appLogger.Info("tracked with metric value", "event", "purchase", "value", 149.99) + + // Track without metric value (count-only event) + // WithoutMetricValue prevents polluting sum/average metrics with zeros + noValueCtx := split.WithoutMetricValue(ctx) + pageViewDetails := openfeature.NewTrackingEventDetails(0). + Add("page", "/dashboard") + ofClient.Track(noValueCtx, "page_view", demoEvalCtx, pageViewDetails) + appLogger.Info("tracked count-only event (nil value)", "event", "page_view") + + // Demonstrate onboarding flow with configuration + appLogger.Info("onboarding flow configuration") + evalCtx := openfeature.NewEvaluationContext("new-user", nil) + onboardingFlow, _ := ofClient.StringValue(ctx, "onboarding_flow", "v1", evalCtx) + appLogger.Info("onboarding flow evaluated", "version", onboardingFlow) + + // Get the configuration + details, _ := ofClient.StringValueDetails(ctx, "onboarding_flow", "v1", evalCtx) + appLogger.Info("onboarding flow details", "variant", details.Variant) + + // Demonstrate maintenance mode flag + appLogger.Info("system flags") + maintenanceMode, _ := ofClient.BooleanValue(ctx, "maintenance_mode", false, evalCtx) + if maintenanceMode { + appLogger.Warn("system is in maintenance mode") + } else { + appLogger.Info("system is operational") + } + + // Show provider health + appLogger.Info("provider health") + metrics := provider.Metrics() + appLogger.Info("health status", + "status", metrics.Status, + "splits_count", metrics.SplitsCount) + + appLogger.Info("localhost mode example completed successfully") + appLogger.Info("tips", + "edit_config", "Edit split.yaml to change flag values", + "network", "No network connection required", + "ci_cd", "Perfect for CI/CD pipelines and unit tests", + "docs", "See README.md for YAML format details") +} diff --git a/examples/localhost/split.yaml b/examples/localhost/split.yaml new file mode 100644 index 0000000..baecb2a --- /dev/null +++ b/examples/localhost/split.yaml @@ -0,0 +1,46 @@ +# Split Localhost Mode - Example Flags +# +# Format: +# - flag_name: +# treatment: "value" # Required: Treatment (must be a string) +# keys: "key1,key2" # Optional: Comma-separated targeting keys +# config: '{"key": "value"}' # Optional: Dynamic Configuration (JSON) +# +# Documentation: https://developer.harness.io/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/go-sdk#yaml + +- new_feature: + treatment: "on" + config: '{"rollout_percentage": 100, "description": "New feature enabled"}' + +- ui_theme: + treatment: "dark" + +- premium_features: + treatment: "on" + config: '{"analytics": true, "ai_assistant": true, "priority_support": true}' + +- max_retries: + treatment: "5" + +- discount_rate: + treatment: "0.15" + +- beta_rollout: + treatment: "off" + keys: "beta-tester-001" # Only specific beta testers + +- onboarding_flow: + treatment: "v2" + config: '{"steps": ["welcome", "profile", "preferences", "done"], "skip_allowed": true}' + +- rate_limit: + treatment: "100" + config: '{"per_minute": 100, "burst": 150}' + +- experimental_algorithm: + treatment: "control" + # Default to control group (no treatment) + +- maintenance_mode: + treatment: "off" + # System-wide maintenance flag \ No newline at end of file diff --git a/go.mod b/go.mod index 859d49d..fa71be4 100644 --- a/go.mod +++ b/go.mod @@ -1,20 +1,31 @@ -module github.com/splitio/split-openfeature-provider-go +module github.com/splitio/split-openfeature-provider-go/v2 -go 1.19 +go 1.25.4 require ( - github.com/open-feature/go-sdk v0.6.0 - github.com/splitio/go-client v6.1.1-0.20210611192632-af2ff877b14a+incompatible - github.com/splitio/go-toolkit v4.2.1-0.20210714181516-85e7c471376a+incompatible + github.com/lmittmann/tint v1.1.2 + github.com/open-feature/go-sdk v1.17.0 + github.com/splitio/go-client/v6 v6.8.1 + github.com/splitio/go-toolkit/v5 v5.4.1 + github.com/stretchr/testify v1.11.1 + go.uber.org/goleak v1.3.0 + golang.org/x/sync v0.17.0 ) require ( - github.com/go-logr/logr v1.2.3 // indirect - github.com/go-redis/redis v6.15.9+incompatible // indirect - github.com/onsi/ginkgo v1.16.5 // indirect - github.com/onsi/gomega v1.20.2 // indirect - github.com/splitio/go-split-commons v3.1.1-0.20210714173613-90097f92c8af+incompatible // indirect - golang.org/x/net v0.7.0 // indirect - golang.org/x/text v0.7.0 // indirect - gopkg.in/yaml.v2 v2.4.0 // indirect + github.com/bits-and-blooms/bitset v1.3.1 // indirect + github.com/bits-and-blooms/bloom/v3 v3.3.1 // indirect + github.com/cespare/xxhash/v2 v2.2.0 // indirect + github.com/davecgh/go-spew v1.1.1 // indirect + github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect + github.com/go-logr/logr v1.4.3 // indirect + github.com/hashicorp/errwrap v1.0.0 // indirect + github.com/hashicorp/go-multierror v1.1.1 // indirect + github.com/pmezard/go-difflib v1.0.0 // indirect + github.com/redis/go-redis/v9 v9.0.4 // indirect + github.com/splitio/go-split-commons/v8 v8.0.0 // indirect + github.com/stretchr/objx v0.5.2 // indirect + go.uber.org/mock v0.6.0 // indirect + golang.org/x/exp v0.0.0-20231006140011-7918f672742d // indirect + gopkg.in/yaml.v3 v3.0.1 // indirect ) diff --git a/go.sum b/go.sum index 30f3304..b72f314 100644 --- a/go.sum +++ b/go.sum @@ -1,107 +1,59 @@ -github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/bits-and-blooms/bitset v1.3.1 h1:y+qrlmq3XsWi+xZqSaueaE8ry8Y127iMxlMfqcK8p0g= +github.com/bits-and-blooms/bitset v1.3.1/go.mod h1:gIdJ4wp64HaoK2YrL1Q5/N7Y16edYb8uY+O0FJTyyDA= +github.com/bits-and-blooms/bloom/v3 v3.3.1 h1:K2+A19bXT8gJR5mU7y+1yW6hsKfNCjcP2uNfLFKncjQ= +github.com/bits-and-blooms/bloom/v3 v3.3.1/go.mod h1:bhUUknWd5khVbTe4UgMCSiOOVJzr3tMoijSK3WwvW90= +github.com/bsm/ginkgo/v2 v2.7.0 h1:ItPMPH90RbmZJt5GtkcNvIRuGEdwlBItdNVoyzaNQao= +github.com/bsm/ginkgo/v2 v2.7.0/go.mod h1:AiKlXPm7ItEHNc/2+OkrNG4E0ITzojb9/xWzvQ9XZ9w= +github.com/bsm/gomega v1.26.0 h1:LhQm+AFcgV2M0WyKroMASzAzCAJVpAxQXv4SaI9a69Y= +github.com/bsm/gomega v1.26.0/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0= +github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44= +github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= -github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo= -github.com/fsnotify/fsnotify v1.4.9 h1:hsms1Qyu0jgnwNXIxa+/V/PDsU6CfLf6CNO8H7IWoS4= -github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ= -github.com/go-logr/logr v1.2.3 h1:2DntVwHkVopvECVRSlL5PSo9eG+cAkDCuckLubN+rq0= -github.com/go-logr/logr v1.2.3/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A= -github.com/go-redis/redis v6.15.9+incompatible h1:K0pv1D7EQUjfyoMql+r/jZqCLizCGKFlFgcHWWmHQjg= -github.com/go-redis/redis v6.15.9+incompatible/go.mod h1:NAIEuMOZ/fxfXJIrKDQDz8wamY7mA7PouImQ2Jvg6kA= -github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg7847qk6SyHyPtNmDHnmrv/HOrqktSC+C9fM+CJOE= -github.com/golang/mock v1.6.0 h1:ErTB+efbowRARo13NNdxyJji2egdxLGQhRaY+DUumQc= -github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U= -github.com/golang/protobuf v1.4.0-rc.1/go.mod h1:ceaxUfeHdC40wWswd/P6IGgMaK3YpKi5j83Wpe3EHw8= -github.com/golang/protobuf v1.4.0-rc.1.0.20200221234624-67d41d38c208/go.mod h1:xKAWHe0F5eneWXFV3EuXVDTCmh+JuBKY0li0aMyXATA= -github.com/golang/protobuf v1.4.0-rc.2/go.mod h1:LlEzMj4AhA7rCAGe4KMBDvJI+AwstrUpVNzEA03Pprs= -github.com/golang/protobuf v1.4.0-rc.4.0.20200313231945-b860323f09d0/go.mod h1:WU3c8KckQ9AFe+yFwt9sWVRKCVIyN9cPHBJSNnbL67w= -github.com/golang/protobuf v1.4.0/go.mod h1:jodUvKwWbYaEsadDk5Fwe5c77LiNKVO9IDvqG2KuDX0= -github.com/golang/protobuf v1.4.2/go.mod h1:oDoupMAO8OvCJWAcko0GGGIgR6R6ocIYbsSw735rRwI= -github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU= -github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU= -github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.8 h1:e6P7q2lk1O+qJJb4BtCQXlK8vWEO8V1ZeuEdJNOqZyg= -github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU= -github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A= -github.com/nxadm/tail v1.4.8 h1:nPr65rt6Y5JFSKQO7qToXr7pePgD6Gwiw05lkbyAQTE= -github.com/nxadm/tail v1.4.8/go.mod h1:+ncqLTQzXmGhMZNUePPaPqPvBxHAIsmXswZKocGu+AU= -github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE= -github.com/onsi/ginkgo v1.12.1/go.mod h1:zj2OWP4+oCPe1qIXoGWkgMRwljMUYCdkwsT2108oapk= -github.com/onsi/ginkgo v1.16.5 h1:8xi0RTUf59SOSfEtZMvwTvXYMzG4gV23XVHOZiXNtnE= -github.com/onsi/ginkgo v1.16.5/go.mod h1:+E8gABHa3K6zRBolWtd+ROzc/U5bkGt0FwiG042wbpU= -github.com/onsi/gomega v1.7.1/go.mod h1:XdKZgCCFLUoM/7CFJVPcG8C1xQ1AJ0vpAezJrB7JYyY= -github.com/onsi/gomega v1.10.1/go.mod h1:iN09h71vgCQne3DLsj+A5owkum+a2tYe+TOCB1ybHNo= -github.com/onsi/gomega v1.20.2 h1:8uQq0zMgLEfa0vRrrBgaJF2gyW9Da9BmfGV+OyUzfkY= -github.com/onsi/gomega v1.20.2/go.mod h1:iYAIXgPSaDHak0LCMA+AWBpIKBr8WZicMxnE8luStNc= -github.com/open-feature/go-sdk v0.4.0 h1:4MC58EBEqsZRPrBfjywTEZXlgiD7lFQVSz0XIJQIRLM= -github.com/open-feature/go-sdk v0.4.0/go.mod h1:rLTOsXIC5wJ/5iVZ0LOTz3/ahJmzxhzWcJTS81AaSqM= -github.com/open-feature/go-sdk v0.5.0 h1:1Y3TYoiZn8yhez9SS6VkS0n9WTfIDst1QDGV92WWHeE= -github.com/open-feature/go-sdk v0.5.0/go.mod h1:5yoSk6QrkAHXKQW9pD+ejxOx3uXUqJwoHmwEK4hlZvk= -github.com/open-feature/go-sdk v0.5.1 h1:gra5dYqcgz3DuyKuOA3TIXS8MuYqNCTVgJpNGemkAQ8= -github.com/open-feature/go-sdk v0.5.1/go.mod h1:5yoSk6QrkAHXKQW9pD+ejxOx3uXUqJwoHmwEK4hlZvk= -github.com/open-feature/go-sdk v0.6.0 h1:/u1XH4msHeChaen65Alfk139/ifu8ZS3mLt37CenR5k= -github.com/open-feature/go-sdk v0.6.0/go.mod h1:5yoSk6QrkAHXKQW9pD+ejxOx3uXUqJwoHmwEK4hlZvk= +github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78= +github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc= +github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI= +github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= +github.com/hashicorp/errwrap v1.0.0 h1:hLrqtEDnRye3+sgx6z4qVLNuviH3MR5aQ0ykNJa/UYA= +github.com/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4= +github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo= +github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM= +github.com/kr/pretty v0.1.0 h1:L/CwN0zerZDmRFUapSPitk6f+Q3+0za1rQkzVuMiMFI= +github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo= +github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= +github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= +github.com/lmittmann/tint v1.1.2 h1:2CQzrL6rslrsyjqLDwD11bZ5OpLBPU+g3G/r5LSfS8w= +github.com/lmittmann/tint v1.1.2/go.mod h1:HIS3gSy7qNwGCj+5oRjAutErFBl4BzdQP6cJZ0NfMwE= +github.com/open-feature/go-sdk v1.17.0 h1:/OUBBw5d9D61JaNZZxb2Nnr5/EJrEpjtKCTY3rspJQk= +github.com/open-feature/go-sdk v1.17.0/go.mod h1:lPxPSu1UnZ4E3dCxZi5gV3et2ACi8O8P+zsTGVsDZUw= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= -github.com/splitio/go-client v6.1.1-0.20210611192632-af2ff877b14a+incompatible h1:ahRviKx2RNNwK2b9NQbD9Iv1DLfHn+KHoBXwmbQ1EgY= -github.com/splitio/go-client v6.1.1-0.20210611192632-af2ff877b14a+incompatible/go.mod h1:dJcPPOO+DlFMELdWAqGUcHTXGvGw0km+UEZJie7Hejk= -github.com/splitio/go-split-commons v3.1.1-0.20210714173613-90097f92c8af+incompatible h1:jaP0z3iiwOYgneBEL7MGkUZNeQgsDiWqa6EBKBgSpQc= -github.com/splitio/go-split-commons v3.1.1-0.20210714173613-90097f92c8af+incompatible/go.mod h1:w1uWXr+HcRVJLeoVyZucm+r3dt0W7zj7Sa9H2TCB3kA= -github.com/splitio/go-toolkit v4.2.1-0.20210714181516-85e7c471376a+incompatible h1:vK8jmQOWqghCU9ZYPjHfrngpugLOFsc4tUMa4OqRk8M= -github.com/splitio/go-toolkit v4.2.1-0.20210714181516-85e7c471376a+incompatible/go.mod h1:Oygm4Hgf3KotB5ZAaXIluLk5HgH2qu723HEPNvszJi8= -github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= -github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA= -github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= -golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= -golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI= -golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= -golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA= -golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= -golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg= -golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= -golang.org/x/net v0.0.0-20200520004742-59133d7f0dd7/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A= -golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU= -golang.org/x/net v0.0.0-20220722155237-a158d28d115b h1:PxfKdU9lEEDYjdIzOtC4qFWgkU2rGHdKlKowJSMN9h0= -golang.org/x/net v0.7.0 h1:rJrUqqhjsgNp7KqAIc25s9pZnjU7TUcSY7HcVZjdn1g= -golang.org/x/net v0.7.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= -golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= -golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= -golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= -golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= -golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= -golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/sys v0.0.0-20190904154756-749cb33beabd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/sys v0.0.0-20191005200804-aed5e4c7ecf9/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/sys v0.0.0-20191120155948-bd437916bb0e/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/sys v0.0.0-20200323222414-85ca7c5b95cd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/sys v0.0.0-20210112080510-489259a85091/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f h1:v4INt8xihDGvnrfjMDVXGxw9wrfxYyCjk0KbXjhR55s= -golang.org/x/sys v0.5.0 h1:MUK/U/4lj1t1oPg0HfuXDN/Z1wv31ZJ/YcPiGccS4DU= -golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= -golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= -golang.org/x/text v0.3.7 h1:olpwvP2KacW1ZWvsR7uQhoyTYvKAupfQrRGBFM352Gk= -golang.org/x/text v0.7.0 h1:4BRB4x83lYWy72KwLD/qYDuTu7q9PjSagHvijDw7cLo= -golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= -golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= -golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= -golang.org/x/tools v0.0.0-20201224043029-2b0845dc783e/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA= -golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= -golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= -golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= -golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= -google.golang.org/protobuf v0.0.0-20200109180630-ec00e32a8dfd/go.mod h1:DFci5gLYBciE7Vtevhsrf46CRTquxDuWsQurQQe4oz8= -google.golang.org/protobuf v0.0.0-20200221191635-4d8936d0db64/go.mod h1:kwYJMbMJ01Woi6D6+Kah6886xMZcty6N08ah7+eCXa0= -google.golang.org/protobuf v0.0.0-20200228230310-ab0ca4ff8a60/go.mod h1:cfTl7dwQJ+fmap5saPgwCLgHXTUD7jkjRqWcaiX5VyM= -google.golang.org/protobuf v1.20.1-0.20200309200217-e05f789c0967/go.mod h1:A+miEFZTKqfCUM6K7xSMQL9OKL/b6hQv+e19PK+JZNE= -google.golang.org/protobuf v1.21.0/go.mod h1:47Nbq4nVaFHyn7ilMalzfO3qCViNmqZ2kzikPIcrTAo= -google.golang.org/protobuf v1.23.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU= -gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= +github.com/redis/go-redis/v9 v9.0.4 h1:FC82T+CHJ/Q/PdyLW++GeCO+Ol59Y4T7R4jbgjvktgc= +github.com/redis/go-redis/v9 v9.0.4/go.mod h1:WqMKv5vnQbRuZstUwxQI195wHy+t4PuXDOjzMvcuQHk= +github.com/splitio/go-client/v6 v6.8.1 h1:wAOmeqrUz63uFBkd64hyob/y+xPuNQypahtvcmvZxOM= +github.com/splitio/go-client/v6 v6.8.1/go.mod h1:2qAeh3AsmnkXcRs+vrBJp35MK1bqhB792dCwJTSprbw= +github.com/splitio/go-split-commons/v8 v8.0.0 h1:wLk5eT6WU2LfxtaWG3ZHlTbNMGWP2eYsZTb1o+tFpkI= +github.com/splitio/go-split-commons/v8 v8.0.0/go.mod h1:vgRGPn0s4RC9/zp1nIn4KeeIEj/K3iXE2fxYQbCk/WI= +github.com/splitio/go-toolkit/v5 v5.4.1 h1:srTyvDBJZMUcJ/KiiQDMyjCuELVgTBh2TGRVn0sOXEE= +github.com/splitio/go-toolkit/v5 v5.4.1/go.mod h1:SifzysrOVDbzMcOE8zjX02+FG5az4FrR3Us/i5SeStw= +github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY= +github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= +github.com/twmb/murmur3 v1.1.6 h1:mqrRot1BRxm+Yct+vavLMou2/iJt0tNVTTC0QoIjaZg= +github.com/twmb/murmur3 v1.1.6/go.mod h1:Qq/R7NUyOfr65zD+6Q5IHKsJLwP7exErjN6lyyq3OSQ= +go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= +go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= +go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y= +go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU= +golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI= +golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo= +golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug= +golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI= +golang.org/x/text v0.30.0 h1:yznKA/E9zq54KzlzBEAWn1NXSQ8DIp/NYMy88xJjl4k= +golang.org/x/text v0.30.0/go.mod h1:yDdHFIX9t+tORqspjENWgzaCVXgk0yYnYuSZ8UzzBVM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= -gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys= -gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkepLTh2hOroT7a+7czfdQ= -gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw= -gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= -gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= -gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= -gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= -gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= +gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo= +gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/helpers.go b/helpers.go new file mode 100644 index 0000000..3d54d95 --- /dev/null +++ b/helpers.go @@ -0,0 +1,428 @@ +package split + +import ( + "context" + "encoding/json" + "sync/atomic" + + of "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/client" +) + +// Factory returns the underlying Split SDK factory for advanced use cases. +// +// ⚠️ ADVANCED USAGE - Lifecycle Management Warning: +// +// The provider manages the Split SDK lifecycle (initialization, shutdown, cleanup). +// When using Factory() directly, you must be aware of these constraints: +// +// 1. DO NOT call factory.Client().Destroy() - the provider owns SDK lifecycle +// 2. DO NOT call factory.Client().BlockUntilReady() - use provider.Status() instead +// 3. The factory is only valid between Init and Shutdown +// 4. After Shutdown(), the client is destroyed and set to nil - factory.Client() will be invalid +// +// See https://github.com/splitio/go-client for Split SDK documentation. +// +// Concurrency Safety: +// Uses read lock for consistency with Status() and Metrics() methods. +// Even though factory is set once during New(), the client field IS set to nil +// during shutdown. The lock prevents returning a factory whose client has been +// destroyed. +// +// Example: +// +// factory := provider.Factory() +// // Use factory for Split-specific features not available in OpenFeature +func (p *Provider) Factory() *client.SplitFactory { + p.mtx.RLock() + defer p.mtx.RUnlock() + return p.factory +} + +// buildSplitAttributes creates an attributes map from FlattenedContext for Split SDK calls. +// Excludes OpenFeature-specific keys that have dedicated uses: +// - targetingKey: used as Split's key parameter (user identifier) +// - trafficType: used for Track() traffic type, not a targeting attribute +func buildSplitAttributes(ec of.FlattenedContext) map[string]any { + attributes := make(map[string]any) + for k, v := range ec { + if k != of.TargetingKey && k != TrafficTypeKey { + attributes[k] = v + } + } + return attributes +} + +// evaluateTreatmentWithConfig evaluates a flag and returns the complete treatment result. +// Returns a non-nil *TreatmentResult{Treatment: "control", Config: nil} if the provider +// is shut down, or the targeting key is missing or invalid. +// +// Concurrency Safety: +// Uses read lock during client call to prevent race with ShutdownWithContext. +// This ensures the client is not destroyed while an evaluation is in progress. +// Checks shutdown flag atomically before acquiring lock for fast-fail during shutdown. +func (p *Provider) evaluateTreatmentWithConfig(ctx context.Context, flag string, ec of.FlattenedContext) *client.TreatmentResult { + // Check shutdown first (fast fail to avoid lock overhead during shutdown) + // If shutdown is in progress, return control treatment immediately + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + return &client.TreatmentResult{Treatment: controlTreatment, Config: nil} + } + + p.logImpressionDisabledNotSupported(ctx, flag) + + key, ok := ec[of.TargetingKey] + if !ok { + p.logger.Debug("targeting key missing", "flag", flag) + return &client.TreatmentResult{Treatment: controlTreatment, Config: nil} + } + + keyStr, ok := key.(string) + if !ok { + p.logger.Debug("targeting key not a string", "flag", flag) + return &client.TreatmentResult{Treatment: controlTreatment, Config: nil} + } + + attributes := buildSplitAttributes(ec) + + // Acquire read lock for client access to prevent concurrent shutdown + // This prevents client.Destroy() from being called during evaluation + p.mtx.RLock() + defer p.mtx.RUnlock() + + // Double-check shutdown after acquiring lock to prevent nil pointer dereference + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + return &client.TreatmentResult{Treatment: controlTreatment, Config: nil} + } + + result := p.client.TreatmentWithConfig(keyStr, flag, attributes) + return &result +} + +// evaluateTreatmentsByFlagSet evaluates all flags in a flag set and returns treatments with configs. +// Returns FlagSetResult (map[flagName]FlagResult). +// Config supports any valid JSON type (objects, arrays, primitives). +// Assumes targeting key validated by caller as string. +// +// Concurrency Safety: +// Uses read lock during client call to prevent race with ShutdownWithContext. +// This ensures the client is not destroyed while an evaluation is in progress. +// Checks shutdown flag atomically before acquiring lock for fast-fail during shutdown. +func (p *Provider) evaluateTreatmentsByFlagSet(ctx context.Context, flagSet string, ec of.FlattenedContext) FlagSetResult { + // Check shutdown first (fast fail to avoid lock overhead during shutdown) + // If shutdown is in progress, return empty map immediately + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + return make(FlagSetResult) + } + + p.logImpressionDisabledNotSupported(ctx, flagSet) + + // Extract targeting key (already validated by caller as string) + keyStr, ok := ec[of.TargetingKey].(string) + if !ok { + p.logger.Error("targeting key not a string (validation invariant violated)", "flag_set", flagSet) + return make(FlagSetResult) + } + + attributes := buildSplitAttributes(ec) + + // Acquire read lock for client access to prevent concurrent shutdown + // This prevents client.Destroy() from being called during evaluation + p.mtx.RLock() + defer p.mtx.RUnlock() + + // Double-check shutdown after acquiring lock to prevent nil pointer dereference + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + return make(FlagSetResult) + } + + results := p.client.TreatmentsWithConfigByFlagSet(keyStr, flagSet, attributes) + + // Transform the results: parse config strings into any valid JSON + transformed := make(FlagSetResult, len(results)) + for flagName, result := range results { + flagResult := FlagResult{ + Treatment: result.Treatment, + } + + flagResult.Config = p.parseConfigJSON(flagName, result.Config) + transformed[flagName] = flagResult + } + + return transformed +} + +// isLocalhostMode checks if the provider is running in localhost mode. +// Localhost mode is detected by checking the OperationMode set by the Split SDK. +// When API key is "localhost", Split SDK automatically sets OperationMode to "localhost". +// This method is concurrent-safe as splitConfig is set once during New() and +// the OperationMode field is not subsequently modified. +func (p *Provider) isLocalhostMode() bool { + return p.splitConfig != nil && p.splitConfig.OperationMode == "localhost" +} + +// evaluateSingleFlagAsObject evaluates a single flag and returns it in flag set structure. +// Returns FlagSetResult (map[flagName]FlagResult) or empty map if flag not found. +// Assumes targeting key validated by caller as string. +// +// Concurrency Safety: +// Uses read lock during client call to prevent race with ShutdownWithContext. +// This ensures the client is not destroyed while an evaluation is in progress. +// Checks shutdown flag atomically before acquiring lock for fast-fail during shutdown. +func (p *Provider) evaluateSingleFlagAsObject(ctx context.Context, flag string, ec of.FlattenedContext) FlagSetResult { + // Check shutdown first (fast fail to avoid lock overhead during shutdown) + // If shutdown is in progress, return empty map immediately + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + return make(FlagSetResult) + } + + p.logImpressionDisabledNotSupported(ctx, flag) + + // Extract targeting key (already validated by caller as string) + keyStr, ok := ec[of.TargetingKey].(string) + if !ok { + p.logger.Error("targeting key not a string (validation invariant violated)", "flag", flag) + return make(FlagSetResult) + } + + attributes := buildSplitAttributes(ec) + + // Acquire read lock for client access to prevent concurrent shutdown + // This prevents client.Destroy() from being called during evaluation + p.mtx.RLock() + defer p.mtx.RUnlock() + + // Double-check shutdown after acquiring lock to prevent nil pointer dereference + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + return make(FlagSetResult) + } + + result := p.client.TreatmentWithConfig(keyStr, flag, attributes) + + // If treatment is control or empty, return empty map (flag not found) + if noTreatment(result.Treatment) { + return make(FlagSetResult) + } + + // Build result in same structure as flag sets + flagResult := FlagResult{ + Treatment: result.Treatment, + Config: p.parseConfigJSON(flag, result.Config), + } + + // Return single-entry map with flag name as key + return FlagSetResult{ + flag: flagResult, + } +} + +// validateEvaluationContext validates the context and evaluation context for common error conditions. +// Returns a ProviderResolutionDetail with an error if validation fails, or an empty detail if valid. +// The caller should check if Error() is not nil to determine if validation failed. +func (p *Provider) validateEvaluationContext(ctx context.Context, ec of.FlattenedContext) of.ProviderResolutionDetail { + if p.Status() != of.ReadyState { + return resolutionDetailProviderNotReady() + } + + if err := ctx.Err(); err != nil { + return resolutionDetailContextCancelled(err) + } + + key, ok := ec[of.TargetingKey] + if !ok { + return resolutionDetailTargetingKeyMissing() + } + + if _, ok := key.(string); !ok { + return resolutionDetailInvalidContext("targeting key must be a string") + } + + return of.ProviderResolutionDetail{} +} + +// noTreatment checks if a treatment is empty or the control treatment. +func noTreatment(treatment string) bool { + return treatment == "" || treatment == controlTreatment +} + +// ======================================== +// OpenFeature Error Code Implementation +// ======================================== +// +// This provider implements all applicable OpenFeature error codes per the spec: +// https://openfeature.dev/specification/types/#error-code +// +// IMPLEMENTED ERROR CODES: +// +// 1. PROVIDER_NOT_READY - Provider has not been initialized or is shut down +// Used in: validateEvaluationContext when p.Status() != ReadyState +// +// 2. FLAG_NOT_FOUND - Flag does not exist in Split +// Used in: All evaluation methods when Split returns "control" treatment +// +// 3. PARSE_ERROR - Treatment value cannot be parsed to requested type +// Used in: Boolean/Int/Float evaluation when strconv.Parse* fails +// Note: Split treatments are always strings, so this is correct for parse failures +// +// 4. TARGETING_KEY_MISSING - Evaluation context has no targeting key +// Used in: validateEvaluationContext when ec[TargetingKey] is not present +// +// 5. INVALID_CONTEXT - Evaluation context is malformed +// Used in: validateEvaluationContext when targeting key exists but is not a string +// +// 6. GENERAL - Context canceled, deadline exceeded, or other errors +// Used in: validateEvaluationContext when ctx.Err() != nil +// +// NOT APPLICABLE ERROR CODES: +// +// 7. TYPE_MISMATCH - Flag value type does not match expected type +// Why not used: Split treatments are untyped strings. We always attempt to parse +// them to the requested type. When parsing fails, it's a PARSE_ERROR (the string +// cannot be parsed), not a TYPE_MISMATCH (Split doesn't have a native type system +// where a flag could be "configured as a boolean" vs "configured as a string"). +// TYPE_MISMATCH would be appropriate for providers with typed flag systems. +// +// 8. PROVIDER_FATAL - Provider encountered an unrecoverable error +// Why not used: Split SDK does not expose fatal runtime errors during evaluation. +// When the SDK cannot evaluate (auth failure, network issues, SDK destroyed), it +// returns the "control" treatment which we handle as FLAG_NOT_FOUND. Provider +// initialization failures are handled by returning errors from New()/Init(), not +// by returning PROVIDER_FATAL during evaluations. + +// resolutionDetailNotFound creates a resolution detail for a flag not found error. +func resolutionDetailNotFound(variant string) of.ProviderResolutionDetail { + return providerResolutionDetailError( + of.NewFlagNotFoundResolutionError("flag not found"), + of.DefaultReason, + variant) +} + +// resolutionDetailParseError creates a resolution detail for a parse error. +func resolutionDetailParseError(variant string) of.ProviderResolutionDetail { + return providerResolutionDetailError( + of.NewParseErrorResolutionError("cannot parse treatment to given type"), + of.ErrorReason, + variant) +} + +// resolutionDetailTargetingKeyMissing creates a resolution detail for missing targeting key. +func resolutionDetailTargetingKeyMissing() of.ProviderResolutionDetail { + return providerResolutionDetailError( + of.NewTargetingKeyMissingResolutionError("targeting key missing"), + of.ErrorReason, + "") +} + +// resolutionDetailContextCancelled creates a resolution detail for canceled context. +func resolutionDetailContextCancelled(err error) of.ProviderResolutionDetail { + return providerResolutionDetailError( + of.NewGeneralResolutionError(err.Error()), + of.ErrorReason, + "") +} + +// resolutionDetailInvalidContext creates a resolution detail for invalid context. +func resolutionDetailInvalidContext(msg string) of.ProviderResolutionDetail { + return providerResolutionDetailError( + of.NewInvalidContextResolutionError(msg), + of.ErrorReason, + "") +} + +// resolutionDetailProviderNotReady creates a resolution detail for provider not ready. +func resolutionDetailProviderNotReady() of.ProviderResolutionDetail { + return providerResolutionDetailError( + of.NewProviderNotReadyResolutionError("provider not initialized"), + of.ErrorReason, + "") +} + +// providerResolutionDetailError creates a resolution detail with an error. +func providerResolutionDetailError(resErr of.ResolutionError, reason of.Reason, variant string) of.ProviderResolutionDetail { + return of.ProviderResolutionDetail{ + ResolutionError: resErr, + Reason: reason, + Variant: variant, + } +} + +// resolutionDetailWithConfig creates resolution detail with Dynamic Configuration. +// Parses config JSON and adds to FlagMetadata. All config values are wrapped as +// {"value": ...} to provide a consistent access pattern via FlagMetadata. +// This is a receiver method (unlike other resolutionDetail* helpers) to enable logging +// of malformed JSON warnings. +// +// ENHANCEMENT NOTE for Split SDK: +// OpenFeature defines 8 semantic reason codes to indicate WHY a flag value was returned: +// - TARGETING_MATCH: Dynamic evaluation based on user targeting rules +// - SPLIT: Pseudorandom assignment (A/B test, traffic allocation) +// - STATIC: Static value with no dynamic evaluation +// - CACHED: Value retrieved from cache +// - DEFAULT: Flag not found, returned default value +// - DISABLED: Flag disabled in management system +// - UNKNOWN: Reason could not be determined +// - ERROR: Error occurred during evaluation +// +// Currently, we use TARGETING_MATCH for ALL successful evaluations because the Split SDK +// does not expose the evaluation reason in its TreatmentResult. The SDK internally knows +// whether the treatment came from: +// - Targeted rule matching (user attributes matched targeting rules) → TARGETING_MATCH +// - Traffic allocation / A/B test (pseudorandom split) → SPLIT +// - Default treatment (no targeting, simple value) → STATIC +// - Cached value (serving from local cache) → CACHED +// +// To properly implement OpenFeature reason codes, the Split Go SDK would need to expose +// this information, perhaps by adding a "Reason" field to the TreatmentResult struct +// returned by TreatmentWithConfig(). This would enable OpenFeature providers to +// accurately report the semantic reason for each evaluation. +func (p *Provider) resolutionDetailWithConfig(flagName, variant string, config *string) of.ProviderResolutionDetail { + detail := of.ProviderResolutionDetail{ + Reason: of.TargetingMatchReason, // See ENHANCEMENT NOTE above + Variant: variant, + } + + // If Dynamic Configuration is present, parse it and add to FlagMetadata + if configData := p.parseConfigJSON(flagName, config); configData != nil { + detail.FlagMetadata = of.FlagMetadata{"value": configData} + } + + return detail +} + +// logImpressionDisabledNotSupported logs a one-time info message if ImpressionDisabled is set. +// Called from evaluation helpers to inform users the option isn't enforced yet. +func (p *Provider) logImpressionDisabledNotSupported(ctx context.Context, _ string) { + evalOpts := GetEvalOptions(ctx) + if evalOpts.ImpressionDisabled { + p.logOnce("impression_disabled", func() { + p.logger.Info("ImpressionDisabled option detected but not yet supported by Split Go SDK", + "note", "will be honored when SDK adds per-evaluation impression control") + }) + } +} + +// parseConfigJSON parses a Split config string into a Go value. +// Returns nil if config is nil, empty, or malformed JSON. +// Logs a warning on parse failure since it indicates invalid configuration in Split UI. +func (p *Provider) parseConfigJSON(flagName string, config *string) any { + if config == nil || *config == "" { + return nil + } + var configData any + if err := json.Unmarshal([]byte(*config), &configData); err != nil { + p.logger.Warn("failed to parse dynamic configuration JSON", + "flag", flagName, + "error", err, + "config_preview", truncateString(*config, 100)) + return nil + } + return configData +} + +// truncateString truncates a string to maxLen bytes, adding "..." if truncated. +// Used for logging previews of potentially large config strings. +func truncateString(s string, maxLen int) string { + if len(s) <= maxLen { + return s + } + return s[:maxLen] + "..." +} diff --git a/lifecycle.go b/lifecycle.go new file mode 100644 index 0000000..affc4f2 --- /dev/null +++ b/lifecycle.go @@ -0,0 +1,490 @@ +package split + +import ( + "context" + "fmt" + "sync/atomic" + "time" + + of "github.com/open-feature/go-sdk/openfeature" +) + +// Init implements StateHandler, which is embedded in ContextAwareStateHandler. +// Required by the interface contract but never called by the OpenFeature SDK +// (it calls InitWithContext instead). Delegates to InitWithContext with a +// timeout derived from BlockUntilReady config + 5s buffer. +func (p *Provider) Init(evaluationContext of.EvaluationContext) error { + // Determine timeout: BlockUntilReady + buffer for SDK operations + timeout := defaultInitTimeout // Defensive fallback (New() guarantees BlockUntilReady > 0) + if p.splitConfig != nil && p.splitConfig.BlockUntilReady > 0 { + timeout = time.Duration(p.splitConfig.BlockUntilReady)*time.Second + initTimeoutBuffer + } + + ctx, cancel := context.WithTimeout(context.Background(), timeout) + defer cancel() + + return p.InitWithContext(ctx, evaluationContext) +} + +// InitWithContext initializes the provider with context support. +// +// This method implements the ContextAwareStateHandler interface and provides +// context-aware initialization that respects cancellation and timeouts. +// +// The context is used to: +// - Cancel initialization if the caller's deadline is exceeded +// - Support graceful shutdown during initialization +// - Propagate cancellation signals from the caller +// +// The OpenFeature SDK calls this method directly since the provider implements +// ContextAwareStateHandler. Init() also delegates here with a derived timeout +// context for direct callers using the StateHandler interface. +func (p *Provider) InitWithContext(ctx context.Context, evaluationContext of.EvaluationContext) error { + _ = evaluationContext // Intentionally unused; required by ContextAwareStateHandler interface + + p.initMu.Lock() + defer p.initMu.Unlock() + + // Check if provider has been shut down - cannot re-initialize after shutdown + // Once Shutdown() is called, the Split SDK client is destroyed and cannot be reused + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + return fmt.Errorf("cannot initialize provider after shutdown: provider has been permanently shut down, create a new provider instance") + } + + // Fast path: check if already initialized with read lock only + p.mtx.RLock() + if p.factory != nil && p.factory.IsReady() { + p.mtx.RUnlock() + p.logger.Debug("provider already initialized") + return nil + } + p.mtx.RUnlock() + + // Use singleflight to ensure only one initialization happens + // All concurrent InitWithContext() calls wait for the same result + _, err, _ := p.initGroup.Do("init", func() (any, error) { + // Double-check after acquiring singleflight lock + p.mtx.RLock() + if p.factory != nil && p.factory.IsReady() { + p.mtx.RUnlock() + p.logger.Debug("provider already initialized (concurrent init detected)") + return nil, nil + } + p.mtx.RUnlock() + + // Block until Split SDK is ready WITH context monitoring + // This can take 10+ seconds, so we monitor ctx.Done() for cancellation + p.logger.Debug("waiting for Split SDK to be ready", "timeout_seconds", p.splitConfig.BlockUntilReady) + + // Run BlockUntilReady in goroutine since it doesn't support context + readyErr := make(chan error, 1) + p.initWg.Add(1) + go func() { + defer p.initWg.Done() // Signal goroutine completion + readyErr <- p.client.BlockUntilReady(p.splitConfig.BlockUntilReady) + }() + + // Wait for either ready or context cancellation + select { + case <-ctx.Done(): + // Context canceled before SDK ready - check if readyErr also completed + select { + case err := <-readyErr: + // SDK completed after context canceled - check result + if err != nil { + // SDK failed AND context canceled - return SDK error + errMsg := fmt.Errorf("split SDK failed to become ready within %d seconds: %w", + p.splitConfig.BlockUntilReady, err) + p.emitEvent(&of.Event{ + ProviderName: p.Metadata().Name, + EventType: of.ProviderError, + ProviderEventDetails: of.ProviderEventDetails{ + Message: errMsg.Error(), + }, + }) + return nil, errMsg + } + // SDK succeeded even though context canceled - proceed with initialization + p.logger.Debug("SDK initialized successfully despite context cancellation") + default: + // SDK still running, context truly canceled - return context error + errMsg := fmt.Errorf("initialization canceled: %w", ctx.Err()) + p.emitEvent(&of.Event{ + ProviderName: p.Metadata().Name, + EventType: of.ProviderError, + ProviderEventDetails: of.ProviderEventDetails{ + Message: errMsg.Error(), + }, + }) + return nil, errMsg + } + case err := <-readyErr: + if err != nil { + errMsg := fmt.Errorf("split SDK failed to become ready within %d seconds: %w", + p.splitConfig.BlockUntilReady, err) + p.emitEvent(&of.Event{ + ProviderName: p.Metadata().Name, + EventType: of.ProviderError, + ProviderEventDetails: of.ProviderEventDetails{ + Message: errMsg.Error(), + }, + }) + return nil, errMsg + } + // SDK succeeded - check if context was canceled during initialization + // If context canceled but SDK ready, we proceed (SDK is usable) + p.logger.Debug("SDK became ready successfully") + } + + // Atomically check shutdown and start monitoring to prevent race condition + // We hold write lock to ensure: + // 1. If Shutdown() is closing stopMonitor, we wait then see shutdown flag + // 2. If we start monitoring, Shutdown() will wait for monitorDone + // This prevents the deadlock where Shutdown waits for monitorDone that never closes + p.mtx.Lock() + + // Check if shutdown happened during BlockUntilReady + // This prevents starting monitoring goroutine after shutdown + if atomic.LoadUint32(&p.shutdown) == shutdownStateActive { + p.mtx.Unlock() + return nil, fmt.Errorf("provider was shut down during initialization") + } + + // Verify factory is ready (final confirmation that entire SDK is ready) + // At this point, factory, client, and manager should all be ready + if !p.factory.IsReady() { + p.mtx.Unlock() + err := fmt.Errorf("split SDK BlockUntilReady succeeded but factory not ready") + p.emitEvent(&of.Event{ + ProviderName: p.Metadata().Name, + EventType: of.ProviderError, + ProviderEventDetails: of.ProviderEventDetails{ + Message: err.Error(), + }, + }) + return nil, err + } + + // Get the number of splits loaded for informational logging + splitCount := 0 + if manager := p.factory.Manager(); manager != nil { + splitNames := manager.SplitNames() + splitCount = len(splitNames) + } + + // Start background monitoring while holding lock (atomic with shutdown check) + // This guarantees that if we start monitoring, Shutdown() will wait for monitorDone + go p.monitorSplitUpdates() + p.mtx.Unlock() + + // Emit PROVIDER_READY event (emitEvent is concurrent-safe) + p.emitEvent(&of.Event{ + ProviderName: p.Metadata().Name, + EventType: of.ProviderReady, + ProviderEventDetails: of.ProviderEventDetails{ + Message: "Split provider initialized successfully", + }, + }) + + p.logger.Info("Split provider ready", "splits_loaded", splitCount) + return nil, nil + }) + + return err +} + +// Shutdown implements StateHandler, which is embedded in ContextAwareStateHandler. +// Required by the interface contract but never called by the OpenFeature SDK +// (it calls ShutdownWithContext instead). Delegates to ShutdownWithContext with a +// default timeout of 30s, or BlockUntilReady duration if it exceeds 30s. +// +// This method performs "best effort" shutdown within the timeout: +// - Provider state is immediately marked as shut down (no new operations allowed) +// - Cleanup operations run within timeout (monitoring stop, SDK destroy, channel close) +// - If timeout expires, cleanup continues in background goroutines +// - Always succeeds (never panics or hangs) +// +// See ShutdownWithContext for detailed best effort shutdown semantics. +func (p *Provider) Shutdown() { + // Determine timeout: use default, or BlockUntilReady if larger + timeout := defaultShutdownTimeout + if p.splitConfig != nil && p.splitConfig.BlockUntilReady > 0 { + configTimeout := time.Duration(p.splitConfig.BlockUntilReady) * time.Second + if configTimeout > timeout { + timeout = configTimeout + } + } + + ctx, cancel := context.WithTimeout(context.Background(), timeout) + defer cancel() + + if err := p.ShutdownWithContext(ctx); err != nil { + p.logger.Warn("shutdown completed with errors", + "error", err, + "note", "StateHandler.Shutdown() has no return value, error cannot be propagated") + } +} + +// ShutdownWithContext gracefully shuts down the provider with context support. +// +// This method implements the ContextAwareStateHandler interface and provides +// context-aware shutdown that respects cancellation and timeouts from the caller. +// +// # Return Values +// +// Returns nil if shutdown completes successfully within the context deadline. +// Returns ctx.Err() if the context expires before shutdown completes (context.DeadlineExceeded +// or context.Canceled). Note that even when an error is returned, the provider is logically +// shut down - the shutdown flag is set immediately and new operations will fail with +// PROVIDER_NOT_READY. +// +// # Shutdown Behavior +// +// The provider state is atomically set to "shut down" immediately upon entry, preventing +// new operations. Cleanup happens on a best-effort basis within the context deadline. +// +// If the context deadline expires during cleanup: +// 1. Warnings are logged about incomplete operations +// 2. ctx.Err() is returned to indicate timeout/cancellation +// 3. Cleanup continues in background goroutines that will eventually complete +// 4. Provider remains logically shut down (Status() returns NotReadyState) +// +// Cleanup operations and their timeout behavior: +// - Event channel close: Always completes immediately +// - Monitoring goroutine: May take up to one monitoring interval to terminate after stopMonitor signal +// - Split SDK Destroy(): May take up to 1 hour in streaming mode (known SDK issue) +// +// The context is used to: +// - Respect the caller's shutdown deadline +// - Cancel long-running cleanup operations +// - Provide graceful shutdown within time constraints +// +// Recommended minimum timeout: 30 seconds to allow monitoring goroutine to exit cleanly. +func (p *Provider) ShutdownWithContext(ctx context.Context) error { + // Check if already shut down and set shutdown flag atomically + // Using atomic operations to prevent race with emitEvent() + if !atomic.CompareAndSwapUint32(&p.shutdown, shutdownStateInactive, shutdownStateActive) { + p.logger.Debug("provider already shut down") + return nil + } + + p.logger.Debug("shutting down Split provider") + + // Track whether any timeout occurred during shutdown + var shutdownErr error + + // Stop background monitoring (if it was started) + // Note: Monitoring only starts after successful initialization + // Atomically close stopMonitor and check if monitoring was started to prevent race condition + // We hold write lock to ensure: + // 1. If Init() is starting monitoring, we wait then close stopMonitor safely + // 2. Our wasInitialized check happens atomically with stopMonitor close + // This prevents the deadlock where we wait for monitorDone that was never started + p.logger.Debug("stopping background monitoring goroutine") + p.mtx.Lock() + close(p.stopMonitor) + wasInitialized := p.factory != nil && p.factory.IsReady() + p.mtx.Unlock() + + if wasInitialized { + p.logger.Debug("waiting for background monitoring to stop") + select { + case <-p.monitorDone: + p.logger.Debug("background monitoring stopped") + case <-ctx.Done(): + shutdownErr = ctx.Err() + p.logger.Warn("context deadline exceeded while waiting for monitoring goroutine, forcing shutdown", + "reason", "monitoring goroutine may still be running", + "error", shutdownErr) + } + } else { + p.logger.Debug("provider was never initialized, skipping monitoring cleanup") + } + + // Wait for initialization goroutine(s) to finish + // This prevents goroutine leak when Init is canceled but BlockUntilReady still running + // BlockUntilReady has a built-in timeout, so initWg.Wait() is bounded + if err := p.waitForInitGoroutines(ctx); err != nil && shutdownErr == nil { + shutdownErr = err + } + + // Destroy Split SDK client and close event channel + // Order is critical: monitoring stopped -> init goroutines done -> NOW safe to close channel and destroy client + operationMode := "unknown" + if p.splitConfig != nil { + operationMode = p.splitConfig.OperationMode + } + p.logger.Debug("destroying Split SDK client", "mode", operationMode) + + destroyStart := time.Now() + destroyDone := make(chan struct{}) + go func() { + defer close(destroyDone) + + p.mtx.Lock() + clientToDestroy := p.client + p.client = nil + close(p.eventStream) + p.mtx.Unlock() + + if clientToDestroy != nil { + func() { + defer func() { + if r := recover(); r != nil { + p.logger.Error("panic during Split SDK destroy", + "panic", r, + "advice", "this may indicate a bug in Split SDK") + } + }() + clientToDestroy.Destroy() + }() + } + elapsed := time.Since(destroyStart).Milliseconds() + p.logger.Debug("Split SDK client destroyed", "duration_ms", elapsed) + }() + + // Wait for either destroy completion or context cancellation + select { + case <-destroyDone: + elapsed := time.Since(destroyStart).Milliseconds() + p.logger.Debug("Split SDK client destroyed successfully", "duration_ms", elapsed) + case <-ctx.Done(): + if shutdownErr == nil { + shutdownErr = ctx.Err() + } + elapsed := time.Since(destroyStart).Milliseconds() + p.logger.Warn("context deadline exceeded during Split SDK destroy, forcing shutdown", + "elapsed_ms", elapsed, + "mode", operationMode, + "reason", "known Split SDK streaming mode issue - SSE connection blocks on read", + "error", shutdownErr) + } + + if shutdownErr != nil { + p.logger.Warn("Split provider shutdown completed with errors", + "error", shutdownErr, + "note", "provider is logically shut down but cleanup may be incomplete") + return shutdownErr + } + + p.logger.Debug("Split provider shut down successfully") + return nil +} + +// waitForInitGoroutines waits for initialization goroutines to complete, +// respecting the context deadline. Returns ctx.Err() if the deadline expires. +func (p *Provider) waitForInitGoroutines(ctx context.Context) error { + p.logger.Debug("waiting for initialization goroutines to complete") + initDone := make(chan struct{}) + go func() { + p.initMu.Lock() + p.initWg.Wait() + p.initMu.Unlock() + close(initDone) + }() + + select { + case <-initDone: + p.logger.Debug("initialization goroutines completed") + return nil + case <-ctx.Done(): + p.logger.Warn("context deadline exceeded while waiting for initialization goroutines", + "error", ctx.Err()) + return ctx.Err() + } +} + +// Status returns the current state of the provider. +// +// Used by the OpenFeature SDK to determine provider readiness. Returns one of: +// - NotReadyState: Provider not initialized or shut down +// - ReadyState: Provider initialized and ready for evaluations +// +// The state is derived from the Split SDK factory's ready status. +// This method is atomic - it checks both shutdown flag and factory state +// together to prevent race conditions during shutdown. +func (p *Provider) Status() of.State { + // Atomic read of shutdown flag and factory state together + // This prevents TOCTOU (time-of-check-time-of-use) race condition + p.mtx.RLock() + shutdown := atomic.LoadUint32(&p.shutdown) == shutdownStateActive + factory := p.factory + p.mtx.RUnlock() + + // If shut down, always NotReady + if shutdown { + return of.NotReadyState + } + + // If we have a factory and it's ready, we're ready + if factory != nil && factory.IsReady() { + return of.ReadyState + } + + // Otherwise, we're not ready + return of.NotReadyState +} + +// ProviderMetrics contains provider health and diagnostic information. +// +// All fields are always populated. SplitsCount is -1 when the provider +// is not ready (not initialized or shut down). +type ProviderMetrics struct { + // Provider is the provider name ("Split"). + Provider string + + // Status is the current provider state (NotReadyState or ReadyState). + Status of.State + + // SplitsCount is the number of split definitions loaded. + // Set to -1 when the provider is not ready. + SplitsCount int + + // Initialized indicates whether the provider is initialized and ready. + Initialized bool + + // Ready indicates whether the provider is ready for evaluations. + // Same as Initialized — both derived from factory ready state and shutdown flag. + Ready bool +} + +// Metrics returns the current metrics and status of the provider. +// +// Example: +// +// m := provider.Metrics() +// fmt.Printf("Provider: %s, Status: %s, Splits: %d\n", +// m.Provider, m.Status, m.SplitsCount) +func (p *Provider) Metrics() ProviderMetrics { + // Atomic read of shutdown flag and factory state together + // This prevents TOCTOU race condition (consistent with Status()) + p.mtx.RLock() + shutdown := atomic.LoadUint32(&p.shutdown) == shutdownStateActive + factory := p.factory + p.mtx.RUnlock() + + isReady := !shutdown && factory != nil && factory.IsReady() + + var status of.State + if isReady { + status = of.ReadyState + } else { + status = of.NotReadyState + } + + m := ProviderMetrics{ + Provider: "Split", + Initialized: isReady, + Status: status, + Ready: isReady, + SplitsCount: -1, + } + + if isReady && factory != nil { + if manager := factory.Manager(); manager != nil { + m.SplitsCount = len(manager.SplitNames()) + } + } + + return m +} diff --git a/lifecycle_edge_cases_test.go b/lifecycle_edge_cases_test.go new file mode 100644 index 0000000..7d30fd6 --- /dev/null +++ b/lifecycle_edge_cases_test.go @@ -0,0 +1,915 @@ +package split + +import ( + "context" + "testing" + "time" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/client" + "github.com/splitio/go-client/v6/splitio/conf" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestInitWithContextTimeout verifies that InitWithContext respects context timeout +// when it's shorter than BlockUntilReady configuration. +// +// This test addresses the edge case where: +// - BlockUntilReady is configured for 10 seconds +// - Context timeout is only 1 second +// - InitWithContext should return context.DeadlineExceeded after ~1 second, not wait 10 seconds +func TestInitWithContextTimeout(t *testing.T) { + // Use invalid API key to force SDK to timeout + // This ensures BlockUntilReady will take the full timeout duration + cfg := conf.Default() + cfg.BlockUntilReady = 10 // 10 seconds timeout in SDK + + provider, err := New("invalid-key-will-timeout", WithSplitConfig(cfg)) + require.NoError(t, err, "Provider creation should succeed") + + // Proper cleanup: Shutdown provider to prevent goroutine leak + defer func() { + shutdownCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + _ = provider.ShutdownWithContext(shutdownCtx) + }() + + // Context with 1 second timeout (shorter than BlockUntilReady) + ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second) + defer cancel() + + start := time.Now() + err = provider.InitWithContext(ctx, openfeature.NewEvaluationContext("", nil)) + elapsed := time.Since(start) + + // Should fail with context error + assert.Error(t, err, "InitWithContext should return error when context times out") + assert.Contains(t, err.Error(), "initialization canceled", "Error should indicate cancellation") + assert.Contains(t, err.Error(), "deadline exceeded", "Error should contain context.DeadlineExceeded") + + // Should respect context timeout (1s), not wait for BlockUntilReady (10s) + assert.Less(t, elapsed, 3*time.Second, + "InitWithContext should return within ~1s (context timeout), not wait 10s (BlockUntilReady)") + assert.Greater(t, elapsed, 800*time.Millisecond, + "InitWithContext should actually wait for context timeout, not return immediately") +} + +// TestInitWithContextCancellationDuringBlockUntilReady verifies that context +// cancellation during BlockUntilReady is handled correctly. +// +// This test addresses the edge case where: +// - InitWithContext is called with a context +// - Context is cancelled WHILE BlockUntilReady is running +// - Should return immediately with context.Canceled error +func TestInitWithContextCancellationDuringBlockUntilReady(t *testing.T) { + cfg := conf.Default() + cfg.BlockUntilReady = 10 // Long timeout to ensure we can cancel during init + + provider, err := New("invalid-key-will-timeout", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Proper cleanup: Shutdown provider to prevent goroutine leak + defer func() { + shutdownCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + _ = provider.ShutdownWithContext(shutdownCtx) + }() + + ctx, cancel := context.WithCancel(context.Background()) + + // Cancel context after 500ms (while BlockUntilReady is running) + go func() { + time.Sleep(500 * time.Millisecond) + cancel() + }() + + start := time.Now() + err = provider.InitWithContext(ctx, openfeature.NewEvaluationContext("", nil)) + elapsed := time.Since(start) + + assert.Error(t, err, "Should return error when context cancelled") + assert.Contains(t, err.Error(), "initialization canceled", "Should indicate cancellation") + + // Should return shortly after cancellation (~500ms), not wait for BlockUntilReady (10s) + assert.Less(t, elapsed, 2*time.Second, + "Should return quickly after context cancellation") + assert.Greater(t, elapsed, 400*time.Millisecond, + "Should actually wait for cancellation, not return immediately") +} + +// TestInitWithContextRaceCondition verifies the fix for the context cancellation race. +// +// This test addresses the critical edge case where: +// - BlockUntilReady completes successfully +// - Context is cancelled at nearly the same moment +// - Both readyErr channel and ctx.Done() are ready +// - select{} randomly chooses which case to execute +// +// Expected behavior: If SDK initialized successfully, we should SUCCEED even if +// context was cancelled, because the SDK is now ready and usable. +func TestInitWithContextRaceCondition(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 // Fast init + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Create context with very short timeout + // Timing is such that context expires RIGHT as BlockUntilReady completes + ctx, cancel := context.WithTimeout(context.Background(), 900*time.Millisecond) + defer cancel() + + err = provider.InitWithContext(ctx, openfeature.NewEvaluationContext("", nil)) + + // The fix ensures this ALWAYS succeeds (SDK is ready) + // Without the fix, this would randomly fail when ctx.Done() is chosen by select + assert.NoError(t, err, "Should succeed when SDK initializes, even if context cancelled during init") + + // Verify provider is actually ready + assert.Equal(t, openfeature.ReadyState, provider.Status(), "Provider should be in Ready state") + + // Cleanup with timeout + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer shutdownCancel() + _ = provider.ShutdownWithContext(shutdownCtx) +} + +// TestShutdownWithContextTimeout verifies that ShutdownWithContext respects +// context timeout without failing prematurely. +// +// This test addresses the edge case where: +// - Context timeout is shorter than monitoring goroutine stop time +// - Previously had hardcoded 5s timeout that would conflict +// - Should not return error if context times out, just log warning and continue +func TestShutdownWithContextTimeout(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Initialize provider + initCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + // Shutdown with extremely short timeout (simulates aggressive shutdown deadline) + // In localhost mode, shutdown is very fast, so we need an unrealistically short timeout + // to trigger the timeout path + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 1*time.Nanosecond) + defer shutdownCancel() + + // Give the timeout a chance to expire before we call Shutdown + time.Sleep(1 * time.Millisecond) + + start := time.Now() + err = provider.ShutdownWithContext(shutdownCtx) + elapsed := time.Since(start) + + // Should return error when context times out + assert.Error(t, err, "ShutdownWithContext should return error when context times out") + assert.ErrorIs(t, err, context.DeadlineExceeded, + "Error should be context.DeadlineExceeded") + + // Should respect context timeout + assert.Less(t, elapsed, 1*time.Second, + "Should return quickly when context times out") + + // Verify provider is shut down (logically) even though cleanup may be incomplete + assert.Equal(t, openfeature.NotReadyState, provider.Status(), + "Provider should be NotReady after shutdown even if context timed out") +} + +// TestShutdownWithContextGracefulStop verifies that ShutdownWithContext +// waits for monitoring goroutine when context allows sufficient time. +func TestShutdownWithContextGracefulStop(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Initialize provider + initCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + // Shutdown with generous timeout (allows clean shutdown) + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 10*time.Second) + defer shutdownCancel() + + err = provider.ShutdownWithContext(shutdownCtx) + + assert.NoError(t, err, "ShutdownWithContext should succeed with sufficient timeout") + assert.Equal(t, openfeature.NotReadyState, provider.Status(), "Provider should be NotReady") +} + +// TestInitShutdownContextInterplay verifies that Init and Shutdown +// contexts are independent and don't interfere with each other. +func TestInitShutdownContextInterplay(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Init with context that expires after initialization + initCtx, initCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer initCancel() + + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + // Cancel init context (should not affect shutdown) + initCancel() + + // Shutdown with different context + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer shutdownCancel() + + err = provider.ShutdownWithContext(shutdownCtx) + assert.NoError(t, err, "Shutdown should succeed with its own context") +} + +// TestInitAfterShutdown verifies that Init cannot be called after Shutdown. +// This ensures the provider cannot be reused after shutdown. +func TestInitAfterShutdown(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Initialize provider + initCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Initial init should succeed") + + // Shutdown provider + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer shutdownCancel() + err = provider.ShutdownWithContext(shutdownCtx) + require.NoError(t, err, "Shutdown should succeed") + + // Attempt to re-initialize after shutdown + reinitCtx, reinitCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer reinitCancel() + err = provider.InitWithContext(reinitCtx, openfeature.NewEvaluationContext("", nil)) + + // Should fail with explicit error about shutdown + assert.Error(t, err, "Init after shutdown should fail") + assert.Contains(t, err.Error(), "cannot initialize provider after shutdown", + "Error should indicate provider was shut down") + assert.Contains(t, err.Error(), "permanently shut down", + "Error should indicate shutdown is permanent") + + // Verify provider status is NotReady + assert.Equal(t, openfeature.NotReadyState, provider.Status(), + "Provider should be NotReady after shutdown") +} + +// TestShutdownBeforeInit verifies that shutting down before initialization is safe. +// This tests the edge case where a provider is created but never initialized. +func TestShutdownBeforeInit(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Shutdown without ever calling Init + shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.ShutdownWithContext(shutdownCtx) + + // Should succeed - shutdown before init is a valid operation + assert.NoError(t, err, "Shutdown before init should succeed") + + // Provider should be in NotReady state + assert.Equal(t, openfeature.NotReadyState, provider.Status(), + "Provider should be NotReady after shutdown") + + // Subsequent Init should fail + initCtx, initCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer initCancel() + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + + assert.Error(t, err, "Init after shutdown should fail") + assert.Contains(t, err.Error(), "cannot initialize provider after shutdown", + "Error should indicate provider was shut down") +} + +// TestConcurrentEvaluationDuringShutdown verifies that evaluations in progress +// are safe during shutdown, and shutdown waits for evaluations to complete. +func TestConcurrentEvaluationDuringShutdown(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Initialize provider + initCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + // Start multiple concurrent evaluations + evaluationsDone := make(chan bool, 10) + ctx := context.Background() + flatCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: "user-123", + } + + for i := 0; i < 10; i++ { + go func() { + // Perform evaluation (should succeed or return PROVIDER_NOT_READY) + result := provider.BooleanEvaluation(ctx, "my-feature", false, flatCtx) + // Don't assert success - evaluation might fail if shutdown happens first + // The important thing is it doesn't panic or hang + _ = result + evaluationsDone <- true + }() + } + + // Give evaluations a brief moment to start + time.Sleep(10 * time.Millisecond) + + // Shutdown while evaluations are in progress + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer shutdownCancel() + err = provider.ShutdownWithContext(shutdownCtx) + assert.NoError(t, err, "Shutdown should succeed even with concurrent evaluations") + + // Wait for all evaluations to complete + for i := 0; i < 10; i++ { + select { + case <-evaluationsDone: + // Evaluation completed + case <-time.After(2 * time.Second): + t.Fatal("Evaluation did not complete within timeout") + } + } + + // Verify provider is shut down + assert.Equal(t, openfeature.NotReadyState, provider.Status()) +} + +// TestMetricsBeforeInit verifies Health() returns correct state before initialization. +func TestMetricsBeforeInit(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Check health before init + metrics := provider.Metrics() + assert.Equal(t, "Split", metrics.Provider) + assert.False(t, metrics.Initialized) + assert.Equal(t, openfeature.NotReadyState, metrics.Status) + assert.False(t, metrics.Ready) + assert.Equal(t, -1, metrics.SplitsCount, "SplitsCount should be -1 before init") +} + +// TestMetricsAfterInit verifies Health() returns correct state after initialization. +func TestMetricsAfterInit(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Initialize + initCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + // Check health after init + metrics := provider.Metrics() + assert.Equal(t, "Split", metrics.Provider) + assert.True(t, metrics.Initialized) + assert.Equal(t, openfeature.ReadyState, metrics.Status) + assert.True(t, metrics.Ready) + assert.Greater(t, metrics.SplitsCount, 0, "SplitsCount should be > 0 for testdata") + + // Cleanup + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer shutdownCancel() + _ = provider.ShutdownWithContext(shutdownCtx) +} + +// TestMetricsAfterShutdown verifies Health() returns correct state after shutdown. +func TestMetricsAfterShutdown(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Initialize + initCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + // Shutdown + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer shutdownCancel() + err = provider.ShutdownWithContext(shutdownCtx) + require.NoError(t, err) + + // Check health after shutdown + metrics := provider.Metrics() + assert.Equal(t, "Split", metrics.Provider) + assert.False(t, metrics.Initialized) + assert.Equal(t, openfeature.NotReadyState, metrics.Status) + assert.False(t, metrics.Ready) + assert.Equal(t, -1, metrics.SplitsCount, "SplitsCount should be -1 after shutdown") +} + +// TestStatusAtomicity verifies that Status() reads shutdown flag and factory state atomically. +// This test runs with -race to detect any race conditions. +func TestStatusAtomicity(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Initialize + initCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + // Concurrently call Status() while shutting down + done := make(chan struct{}) + goroutinesDone := make(chan struct{}, 5) + + // Goroutines calling Status() repeatedly + for i := 0; i < 5; i++ { + go func() { + defer func() { goroutinesDone <- struct{}{} }() + for { + select { + case <-done: + return + default: + // Just call Status(), don't store the result + _ = provider.Status() + // Small sleep to avoid tight loop + time.Sleep(1 * time.Millisecond) + } + } + }() + } + + // Give Status() calls a moment to start + time.Sleep(10 * time.Millisecond) + + // Shutdown + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer shutdownCancel() + err = provider.ShutdownWithContext(shutdownCtx) + assert.NoError(t, err) + + // Stop Status() calls and wait for all goroutines to finish + close(done) + for i := 0; i < 5; i++ { + <-goroutinesDone + } + + // Verify final status is NotReady + finalStatus := provider.Status() + assert.Equal(t, openfeature.NotReadyState, finalStatus, + "Final status should be NotReady after shutdown") + + // The test passes if no race detector warnings occur + // All intermediate statuses should be either Ready or NotReady (no undefined states) +} + +// TestDoubleShutdown verifies that calling Shutdown multiple times is safe. +func TestDoubleShutdown(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Initialize + initCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + // First shutdown + shutdownCtx1, cancel1 := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel1() + err = provider.ShutdownWithContext(shutdownCtx1) + assert.NoError(t, err, "First shutdown should succeed") + + // Second shutdown (should be idempotent) + shutdownCtx2, cancel2 := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel2() + err = provider.ShutdownWithContext(shutdownCtx2) + assert.NoError(t, err, "Second shutdown should succeed (idempotent)") + + // Verify provider is still NotReady + assert.Equal(t, openfeature.NotReadyState, provider.Status()) +} + +// TestInitIdempotency verifies that calling Init when already initialized +// returns immediately without re-initializing or starting duplicate monitoring goroutines. +func TestInitIdempotency(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // First Init + initCtx1, cancel1 := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel1() + err = provider.InitWithContext(initCtx1, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "First init should succeed") + assert.Equal(t, openfeature.ReadyState, provider.Status()) + + // Second Init (should hit fast path, return immediately) + initCtx2, cancel2 := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel2() + start := time.Now() + err = provider.InitWithContext(initCtx2, openfeature.NewEvaluationContext("", nil)) + elapsed := time.Since(start) + + // Should succeed immediately (fast path) + assert.NoError(t, err, "Second init should succeed (idempotent)") + assert.Less(t, elapsed, 100*time.Millisecond, + "Second init should return immediately via fast path, not wait for BlockUntilReady") + assert.Equal(t, openfeature.ReadyState, provider.Status()) + + // Third Init (also fast path) + initCtx3, cancel3 := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel3() + err = provider.InitWithContext(initCtx3, openfeature.NewEvaluationContext("", nil)) + assert.NoError(t, err, "Third init should succeed (idempotent)") + + // Cleanup + shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + _ = provider.ShutdownWithContext(shutdownCtx) +} + +// TestConcurrentInit verifies that multiple concurrent Init calls are handled +// correctly using singleflight - only ONE initialization happens. +func TestConcurrentInit(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Start 10 concurrent Init calls + const numGoroutines = 10 + results := make(chan error, numGoroutines) + start := make(chan struct{}) + + for i := 0; i < numGoroutines; i++ { + go func() { + <-start // Synchronize all goroutines to start at once + initCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err := provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + results <- err + }() + } + + // Start all goroutines at once + close(start) + + // Collect all results + var successCount int + for i := 0; i < numGoroutines; i++ { + err := <-results + if err == nil { + successCount++ + } + } + + // All Init calls should succeed (singleflight ensures only one actual init) + assert.Equal(t, numGoroutines, successCount, "All Init calls should succeed") + + // Verify provider is ready + assert.Equal(t, openfeature.ReadyState, provider.Status()) + + // Cleanup + shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + _ = provider.ShutdownWithContext(shutdownCtx) +} + +// TestShutdownDuringInit verifies that calling Shutdown while Init is in progress +// is handled safely without panics or hangs. +func TestShutdownDuringInit(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 2 // Longer to give shutdown time to race + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Start Init in background + initDone := make(chan error, 1) + go func() { + initCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + err := provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + initDone <- err + }() + + // Give Init a moment to start BlockUntilReady + time.Sleep(100 * time.Millisecond) + + // Call Shutdown while Init is in progress + shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.ShutdownWithContext(shutdownCtx) + + // Shutdown should succeed (may complete before init, or after) + assert.NoError(t, err, "Shutdown should succeed even during init") + + // Wait for Init to complete + select { + case initErr := <-initDone: + // Init might succeed (if it completed before shutdown) + // or fail (if shutdown happened first) + // Either outcome is acceptable - the important thing is no panic/hang + _ = initErr + case <-time.After(15 * time.Second): + t.Fatal("Init did not complete within timeout") + } + + // Final status should be NotReady (shutdown completed) + assert.Equal(t, openfeature.NotReadyState, provider.Status()) +} + +// TestFactoryAccessorDuringShutdown verifies that Factory() accessor is safe +// to call concurrently with Shutdown(). +func TestFactoryAccessorDuringShutdown(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = "testdata/split.yaml" + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + + // Initialize + initCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.InitWithContext(initCtx, openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + // Concurrently access Factory() while shutting down + done := make(chan struct{}) + goroutinesDone := make(chan int, 5) + + // Goroutines calling Factory() repeatedly + for i := 0; i < 5; i++ { + go func() { + count := 0 + defer func() { goroutinesDone <- count }() + for { + select { + case <-done: + return + default: + var factory *client.SplitFactory = provider.Factory() + if factory != nil { + count++ + } + time.Sleep(1 * time.Millisecond) + } + } + }() + } + + // Give Factory() calls a moment to start + time.Sleep(10 * time.Millisecond) + + // Shutdown + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second) + defer shutdownCancel() + err = provider.ShutdownWithContext(shutdownCtx) + assert.NoError(t, err) + + // Stop Factory() calls and wait for all goroutines + close(done) + totalCalls := 0 + for i := 0; i < 5; i++ { + totalCalls += <-goroutinesDone + } + + // Verify we got some factory results (test passed if no data race) + assert.Greater(t, totalCalls, 0, "Should have retrieved factory at least once") +} + +// TestEventChannelClosedOnShutdown verifies that the event channel is properly +// closed when the provider is shut down, preventing deadlocks for consumers +// using for...range loops. +// +// This test addresses a critical requirement from the OpenFeature specification: +// the event channel must be closed during shutdown to signal consumers that +// no more events will be sent. +func TestEventChannelClosedOnShutdown(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Provider creation should succeed") + + // Initialize the provider + ctx := context.Background() + err = provider.InitWithContext(ctx, openfeature.NewEvaluationContext("test-user", nil)) + require.NoError(t, err, "Init should succeed") + + // Get the event channel + eventChan := provider.EventChannel() + require.NotNil(t, eventChan, "EventChannel should not be nil") + + // Start a goroutine that ranges over the event channel + // This simulates a typical consumer pattern + consumerDone := make(chan struct{}) + receivedEvents := 0 + + go func() { + defer close(consumerDone) + for range eventChan { + receivedEvents++ + } + // When the channel is closed, the range loop exits and we close consumerDone + }() + + // Shutdown the provider + shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.ShutdownWithContext(shutdownCtx) + assert.NoError(t, err, "Shutdown should succeed") + + // Wait for the consumer goroutine to exit (with timeout) + // If the channel is not closed, this will timeout + select { + case <-consumerDone: + // Success - the range loop exited because the channel was closed + t.Logf("Consumer goroutine exited cleanly after receiving %d events", receivedEvents) + case <-time.After(2 * time.Second): + t.Fatal("Consumer goroutine did not exit - event channel was not closed on shutdown") + } + + // Verify we received at least the PROVIDER_READY event + assert.Greater(t, receivedEvents, 0, "Should have received at least one event") +} + +// TestEventChannelMultipleConsumers verifies that multiple goroutines +// ranging over the event channel all exit cleanly when the provider shuts down. +func TestEventChannelMultipleConsumers(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Provider creation should succeed") + + // Initialize the provider + ctx := context.Background() + err = provider.InitWithContext(ctx, openfeature.NewEvaluationContext("test-user", nil)) + require.NoError(t, err, "Init should succeed") + + // Get the event channel + eventChan := provider.EventChannel() + + // Start multiple consumer goroutines + numConsumers := 5 + consumersDone := make(chan int, numConsumers) + + for i := 0; i < numConsumers; i++ { + go func() { + count := 0 + for range eventChan { + count++ + } + consumersDone <- count + }() + } + + // Give consumers a moment to start + time.Sleep(100 * time.Millisecond) + + // Shutdown the provider + shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.ShutdownWithContext(shutdownCtx) + assert.NoError(t, err, "Shutdown should succeed") + + // Wait for all consumers to exit (with timeout) + timeout := time.After(2 * time.Second) + for i := 0; i < numConsumers; i++ { + select { + case count := <-consumersDone: + t.Logf("Consumer %d exited cleanly after receiving %d events", i, count) + case <-timeout: + t.Fatalf("Consumer %d did not exit - event channel was not closed on shutdown", i) + } + } +} + +// TestEventChannelClosedBeforeInit verifies that shutdown works correctly +// even when called before initialization (edge case). +func TestEventChannelClosedBeforeInit(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Provider creation should succeed") + + // Get the event channel before init + eventChan := provider.EventChannel() + require.NotNil(t, eventChan, "EventChannel should not be nil") + + // Start consumer before init + consumerDone := make(chan struct{}) + go func() { + defer close(consumerDone) + for range eventChan { + // Consume events + } + }() + + // Shutdown without initializing + shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err = provider.ShutdownWithContext(shutdownCtx) + assert.NoError(t, err, "Shutdown should succeed even without init") + + // Verify consumer exits + select { + case <-consumerDone: + // Success + case <-time.After(2 * time.Second): + t.Fatal("Consumer did not exit - event channel was not closed") + } +} + +// TestShutdownIdempotencyWithEventChannel verifies that calling shutdown +// multiple times doesn't cause panics (double-close on channel). +func TestShutdownIdempotencyWithEventChannel(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.BlockUntilReady = 1 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Provider creation should succeed") + + // Initialize + ctx := context.Background() + err = provider.InitWithContext(ctx, openfeature.NewEvaluationContext("test-user", nil)) + require.NoError(t, err, "Init should succeed") + + // First shutdown + shutdownCtx1, cancel1 := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel1() + err = provider.ShutdownWithContext(shutdownCtx1) + assert.NoError(t, err, "First shutdown should succeed") + + // Second shutdown - should not panic from double-close + shutdownCtx2, cancel2 := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel2() + err = provider.ShutdownWithContext(shutdownCtx2) + assert.NoError(t, err, "Second shutdown should succeed without panic") + + // Third shutdown - verify idempotency + shutdownCtx3, cancel3 := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel3() + err = provider.ShutdownWithContext(shutdownCtx3) + assert.NoError(t, err, "Third shutdown should succeed without panic") +} diff --git a/lifecycle_test.go b/lifecycle_test.go new file mode 100644 index 0000000..8d89ad4 --- /dev/null +++ b/lifecycle_test.go @@ -0,0 +1,249 @@ +package split + +import ( + "context" + "testing" + "time" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/conf" + "github.com/splitio/go-toolkit/v5/logging" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestProviderInit tests the Init method and lifecycle initialization. +func TestProviderInit(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + + assert.Equal(t, openfeature.NotReadyState, provider.Status(), "Provider should start in NotReady state") + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + assert.Equal(t, openfeature.ReadyState, provider.Status(), "Provider should be Ready after Init") + + // Calling Init again should be idempotent + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + assert.NoError(t, err, "Second Init call should succeed (idempotent)") + + _ = provider.ShutdownWithContext(context.Background()) +} + +// TestProviderShutdown tests the Shutdown method and resource cleanup. +func TestProviderShutdown(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + assert.Equal(t, openfeature.ReadyState, provider.Status(), "Provider should be Ready after Init") + + _ = provider.ShutdownWithContext(context.Background()) + + assert.Equal(t, openfeature.NotReadyState, provider.Status(), "Provider should be NotReady after Shutdown") + + // Calling Shutdown again should be idempotent (should not panic) + _ = provider.ShutdownWithContext(context.Background()) +} + +// TestProviderShutdownTimeout tests that Shutdown completes within reasonable time. +func TestProviderShutdownTimeout(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + done := make(chan struct{}) + go func() { + _ = provider.ShutdownWithContext(context.Background()) + close(done) + }() + + select { + case <-done: + // Success - shutdown completed + case <-time.After(10 * time.Second): + t.Fatal("Shutdown did not complete within 10 seconds") + } +} + +// TestProviderEventChannel tests the EventChannel method and event emission. +func TestProviderEventChannel(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + + eventChan := provider.EventChannel() + require.NotNil(t, eventChan, "EventChannel() should not return nil") + + events := make([]openfeature.Event, 0) + done := make(chan struct{}) + go func() { + for event := range eventChan { + events = append(events, event) + if event.EventType == openfeature.ProviderReady { + close(done) + return + } + } + }() + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + select { + case <-done: + // Success - received ProviderReady event + case <-time.After(1 * time.Second): + t.Error("Timeout waiting for ProviderReady event") + } + + assert.NotEmpty(t, events, "Should receive at least one event") + + foundReady := false + for _, event := range events { + if event.EventType == openfeature.ProviderReady { + foundReady = true + assert.Equal(t, providerNameSplit, event.ProviderName, "Provider name should be 'Split'") + } + } + assert.True(t, foundReady, "Should receive ProviderReady event") + + _ = provider.ShutdownWithContext(context.Background()) +} + +// TestProviderHealth tests the Health method. +func TestProviderHealth(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + + // Health before Init + metrics := provider.Metrics() + assert.Equal(t, providerNameSplit, metrics.Provider, "Provider name should be 'Split'") + assert.False(t, metrics.Initialized, "Should not be initialized before Init") + assert.Equal(t, openfeature.NotReadyState, metrics.Status, "Status should be NOT_READY") + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + // Metrics after Init + metrics = provider.Metrics() + assert.True(t, metrics.Initialized, "Should be initialized after Init") + assert.Equal(t, openfeature.ReadyState, metrics.Status, "Status should be READY") + assert.True(t, metrics.Ready, "Should be ready") + assert.Greater(t, metrics.SplitsCount, 0, "splits_count should be greater than 0") + + _ = provider.ShutdownWithContext(context.Background()) +} + +// TestInitWrapper tests the Init() method (StateHandler interface). +// Verifies it delegates to InitWithContext with a derived timeout. +func TestInitWrapper(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + + assert.Equal(t, openfeature.NotReadyState, provider.Status(), "Provider should start in NotReady state") + + // Call Init (non-context version) + err = provider.Init(openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + assert.Equal(t, openfeature.ReadyState, provider.Status(), "Provider should be Ready after Init") + + // Calling Init again should be idempotent + err = provider.Init(openfeature.NewEvaluationContext("", nil)) + assert.NoError(t, err, "Second Init call should succeed (idempotent)") + + _ = provider.ShutdownWithContext(context.Background()) +} + +// TestShutdownWrapper tests the Shutdown() method (StateHandler interface). +// Verifies it delegates to ShutdownWithContext with a derived timeout. +func TestShutdownWrapper(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + assert.Equal(t, openfeature.ReadyState, provider.Status(), "Provider should be Ready after Init") + + // Call Shutdown (non-context version) - should not panic + provider.Shutdown() + + assert.Equal(t, openfeature.NotReadyState, provider.Status(), "Provider should be NotReady after Shutdown") + + // Calling Shutdown again should be idempotent (should not panic) + provider.Shutdown() +} + +// TestProviderFactoryGetter tests the Factory method. +func TestProviderFactoryGetter(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Failed to initialize provider") + + factory := provider.Factory() + require.NotNil(t, factory, "Factory should not be nil") + + splitClient := factory.Client() + require.NotNil(t, splitClient, "Client should not be nil") + + err = splitClient.Track("test-user", "test-traffic", "test-event", 1.0, nil) + assert.NoError(t, err, "Track call should succeed") + + manager := factory.Manager() + require.NotNil(t, manager, "Manager should not be nil") + + splitNames := manager.SplitNames() + assert.NotEmpty(t, splitNames, "Should have split definitions loaded") + + assert.True(t, factory.IsReady(), "Factory should be ready") + + _ = provider.ShutdownWithContext(context.Background()) +} diff --git a/logging.go b/logging.go new file mode 100644 index 0000000..fd386cd --- /dev/null +++ b/logging.go @@ -0,0 +1,105 @@ +package split + +import ( + "fmt" + "log/slog" +) + +// SlogToSplitAdapter adapts Go's standard *slog.Logger to Split SDK's LoggerInterface. +// +// This adapter allows the Split SDK to use the same logger configured for the application +// via slog.SetDefault(), ensuring consistent logging across the provider and Split SDK. +// All Split SDK log levels are mapped directly to slog levels (Error→Error, Warning→Warn, etc.) +// +// This type is exported for advanced use cases where you need to configure the Split SDK +// client directly with structured logging support. +type SlogToSplitAdapter struct { + logger *slog.Logger +} + +// NewSplitLogger creates a Split SDK logger adapter from a slog.Logger. +// +// This function allows you to use Go's structured logging (slog) with the Split SDK +// by configuring the SDK before creating the provider. +// +// Example usage with custom logger configuration: +// +// import ( +// "log/slog" +// "github.com/splitio/go-client/v6/splitio/conf" +// split "github.com/splitio/split-openfeature-provider-go/v2" +// ) +// +// // Configure custom slog logger +// logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{ +// Level: slog.LevelInfo, +// })) +// +// // Configure Split SDK with slog adapter +// cfg := conf.Default() +// cfg.Logger = split.NewSplitLogger(logger) // Use slog adapter +// cfg.BlockUntilReady = 10 +// +// // Create provider with configured logging +// provider, _ := split.New("YOUR_SDK_KEY", split.WithSplitConfig(cfg)) +// defer provider.Shutdown() +// +// For local development/testing, you can use localhost mode with a local splits file. +// +// If logger is nil, slog.Default() is used. +func NewSplitLogger(logger *slog.Logger) *SlogToSplitAdapter { + if logger == nil { + logger = slog.Default() + } + return &SlogToSplitAdapter{logger: logger} +} + +// Error logs an error message. +// If multiple arguments are provided, the first is treated as the message +// and remaining arguments are logged as structured "details" field. +func (a *SlogToSplitAdapter) Error(msg ...any) { + a.log(a.logger.Error, msg...) +} + +// Warning logs a warning message. +// If multiple arguments are provided, the first is treated as the message +// and remaining arguments are logged as structured "details" field. +func (a *SlogToSplitAdapter) Warning(msg ...any) { + a.log(a.logger.Warn, msg...) +} + +// Info logs an informational message. +// If multiple arguments are provided, the first is treated as the message +// and remaining arguments are logged as structured "details" field. +func (a *SlogToSplitAdapter) Info(msg ...any) { + a.log(a.logger.Info, msg...) +} + +// Debug logs a debug message. +// If multiple arguments are provided, the first is treated as the message +// and remaining arguments are logged as structured "details" field. +func (a *SlogToSplitAdapter) Debug(msg ...any) { + a.log(a.logger.Debug, msg...) +} + +// Verbose logs a verbose message (mapped to Debug level in slog). +// If multiple arguments are provided, the first is treated as the message +// and remaining arguments are logged as structured "details" field. +func (a *SlogToSplitAdapter) Verbose(msg ...any) { + a.log(a.logger.Debug, msg...) +} + +// log is a helper that preserves structured logging when multiple arguments are provided. +// Single argument: logged as message only. +// Multiple arguments: first as message, rest as structured "details" field. +func (a *SlogToSplitAdapter) log(logFunc func(string, ...any), msg ...any) { + if len(msg) == 0 { + logFunc("") + return + } + if len(msg) == 1 { + logFunc(fmt.Sprint(msg[0])) + return + } + logFunc(fmt.Sprint(msg[0]), "details", msg[1:]) +} diff --git a/logging_test.go b/logging_test.go new file mode 100644 index 0000000..2a99b75 --- /dev/null +++ b/logging_test.go @@ -0,0 +1,363 @@ +package split + +import ( + "bytes" + "encoding/json" + "log/slog" + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestNewSplitLoggerCreatesValidAdapter verifies factory function creates valid adapter. +func TestNewSplitLoggerCreatesValidAdapter(t *testing.T) { + t.Run("with custom logger", func(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, nil)) + adapter := NewSplitLogger(logger) + + require.NotNil(t, adapter) + assert.NotNil(t, adapter.logger) + }) + + t.Run("with nil logger uses default", func(t *testing.T) { + adapter := NewSplitLogger(nil) + + require.NotNil(t, adapter) + assert.NotNil(t, adapter.logger) + assert.Equal(t, slog.Default(), adapter.logger) + }) +} + +// TestLogAdapterLogsAtCorrectLevel verifies all log levels produce correct output. +func TestLogAdapterLogsAtCorrectLevel(t *testing.T) { + tests := []struct { + logFunc func(*SlogToSplitAdapter, ...any) + name string + expectedLevel string + message string + slogLevel slog.Level + }{ + { + name: "Error level", + logFunc: (*SlogToSplitAdapter).Error, + expectedLevel: "ERROR", + slogLevel: slog.LevelError, + message: "test error message", + }, + { + name: "Warning level", + logFunc: (*SlogToSplitAdapter).Warning, + expectedLevel: "WARN", + slogLevel: slog.LevelWarn, + message: "test warning message", + }, + { + name: "Info level", + logFunc: (*SlogToSplitAdapter).Info, + expectedLevel: "INFO", + slogLevel: slog.LevelInfo, + message: "test info message", + }, + { + name: "Debug level", + logFunc: (*SlogToSplitAdapter).Debug, + expectedLevel: "DEBUG", + slogLevel: slog.LevelDebug, + message: "test debug message", + }, + { + name: "Verbose maps to Debug level", + logFunc: (*SlogToSplitAdapter).Verbose, + expectedLevel: "DEBUG", + slogLevel: slog.LevelDebug, + message: "test verbose message", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{ + Level: tt.slogLevel, + })) + adapter := NewSplitLogger(logger) + + tt.logFunc(adapter, tt.message) + + logOutput := buf.String() + assert.Contains(t, logOutput, tt.expectedLevel) + assert.Contains(t, logOutput, tt.message) + + // Verify JSON structure + var logEntry map[string]any + err := json.Unmarshal([]byte(logOutput), &logEntry) + require.NoError(t, err) + assert.Equal(t, tt.expectedLevel, logEntry["level"]) + assert.Equal(t, tt.message, logEntry["msg"]) + }) + } +} + +// TestLogAdapterPreservesStructuredData verifies structured logging with multiple arguments. +func TestLogAdapterPreservesStructuredData(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{ + Level: slog.LevelInfo, + })) + adapter := NewSplitLogger(logger) + + // Log with structured details + adapter.Info("operation completed", "duration_ms", 150, "success", true) + + logOutput := buf.String() + + // Verify JSON structure + var logEntry map[string]any + err := json.Unmarshal([]byte(logOutput), &logEntry) + require.NoError(t, err) + + assert.Equal(t, "INFO", logEntry["level"]) + assert.Equal(t, "operation completed", logEntry["msg"]) + + // Verify structured details field exists + require.Contains(t, logEntry, "details") + details, ok := logEntry["details"].([]any) + require.True(t, ok, "details should be an array") + + // Verify details contain the arguments + require.Len(t, details, 4) + assert.Equal(t, "duration_ms", details[0]) + assert.Equal(t, float64(150), details[1]) // JSON numbers are float64 + assert.Equal(t, "success", details[2]) + assert.Equal(t, true, details[3]) +} + +// TestLogAdapterDoesNotCreateDetailsForSingleArgument verifies single argument behavior. +func TestLogAdapterDoesNotCreateDetailsForSingleArgument(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{ + Level: slog.LevelInfo, + })) + adapter := NewSplitLogger(logger) + + adapter.Info("simple message") + + logOutput := buf.String() + + // Verify JSON structure + var logEntry map[string]any + err := json.Unmarshal([]byte(logOutput), &logEntry) + require.NoError(t, err) + + assert.Equal(t, "INFO", logEntry["level"]) + assert.Equal(t, "simple message", logEntry["msg"]) + + // Should NOT have details field for single argument + assert.NotContains(t, logEntry, "details") +} + +// TestLogAdapterSupportsStructuredLoggingAtAllLevels verifies all levels support structured data. +func TestLogAdapterSupportsStructuredLoggingAtAllLevels(t *testing.T) { + tests := []struct { + name string + logFunc func(*SlogToSplitAdapter, ...any) + expected string + }{ + {"Error", (*SlogToSplitAdapter).Error, "ERROR"}, + {"Warning", (*SlogToSplitAdapter).Warning, "WARN"}, + {"Info", (*SlogToSplitAdapter).Info, "INFO"}, + {"Debug", (*SlogToSplitAdapter).Debug, "DEBUG"}, + {"Verbose", (*SlogToSplitAdapter).Verbose, "DEBUG"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{ + Level: slog.LevelDebug, + })) + adapter := NewSplitLogger(logger) + + tt.logFunc(adapter, "message", "key", "value") + + logOutput := buf.String() + + var logEntry map[string]any + err := json.Unmarshal([]byte(logOutput), &logEntry) + require.NoError(t, err) + + assert.Equal(t, tt.expected, logEntry["level"]) + assert.Equal(t, "message", logEntry["msg"]) + assert.Contains(t, logEntry, "details") + }) + } +} + +// TestLogAdapterCreatesStructuredDetailsFromMultipleArguments verifies details array creation. +func TestLogAdapterCreatesStructuredDetailsFromMultipleArguments(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{ + Level: slog.LevelInfo, + })) + adapter := NewSplitLogger(logger) + + adapter.Info("message", " ", "with", " ", "multiple", " ", "args") + + logOutput := buf.String() + + // With structured logging, first arg is message, rest are details + var logEntry map[string]any + err := json.Unmarshal([]byte(logOutput), &logEntry) + require.NoError(t, err) + + assert.Equal(t, "message", logEntry["msg"]) + assert.Contains(t, logEntry, "details") + details, ok := logEntry["details"].([]any) + require.True(t, ok) + assert.Len(t, details, 6) // All the remaining arguments +} + +// TestLogAdapterFiltersLogsByLevel verifies log level filtering works correctly. +func TestLogAdapterFiltersLogsByLevel(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{ + Level: slog.LevelWarn, // Only warn and above + })) + adapter := NewSplitLogger(logger) + + adapter.Debug("debug message") + adapter.Info("info message") + adapter.Warning("warning message") + adapter.Error("error message") + + logOutput := buf.String() + + // Debug and Info should be filtered out + assert.NotContains(t, logOutput, "debug message") + assert.NotContains(t, logOutput, "info message") + + // Warning and Error should be present + assert.Contains(t, logOutput, "warning message") + assert.Contains(t, logOutput, "error message") +} + +// TestLogAdapterHandlesEmptyMessage verifies empty message logging. +func TestLogAdapterHandlesEmptyMessage(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{ + Level: slog.LevelInfo, + })) + adapter := NewSplitLogger(logger) + + adapter.Info() + + logOutput := buf.String() + // Empty message should still produce a log entry + assert.Contains(t, logOutput, "INFO") + + var logEntry map[string]any + err := json.Unmarshal([]byte(logOutput), &logEntry) + require.NoError(t, err) + assert.Equal(t, "", logEntry["msg"]) +} + +// TestLogAdapterEscapesSpecialCharactersInJSON verifies JSON escaping. +func TestLogAdapterEscapesSpecialCharactersInJSON(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{ + Level: slog.LevelInfo, + })) + adapter := NewSplitLogger(logger) + + specialMsg := "message with \"quotes\" and \n newlines" + adapter.Info(specialMsg) + + logOutput := buf.String() + + // Verify JSON is valid despite special characters + var logEntry map[string]any + err := json.Unmarshal([]byte(logOutput), &logEntry) + require.NoError(t, err) + + // Message should be properly escaped in JSON + assert.Contains(t, logEntry["msg"], "quotes") +} + +// TestLogAdapterFormatsNonStringArgumentsCorrectly verifies non-string formatting. +func TestLogAdapterFormatsNonStringArgumentsCorrectly(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{ + Level: slog.LevelInfo, + })) + adapter := NewSplitLogger(logger) + + adapter.Info("count:", 42, "enabled:", true, "rate:", 3.14) + + logOutput := buf.String() + assert.Contains(t, logOutput, "count:") + assert.Contains(t, logOutput, "42") + assert.Contains(t, logOutput, "enabled:") + assert.Contains(t, logOutput, "true") + assert.Contains(t, logOutput, "rate:") + assert.Contains(t, logOutput, "3.14") +} + +// TestLogAdapterWorksWithTextHandler verifies text handler compatibility. +func TestLogAdapterWorksWithTextHandler(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewTextHandler(&buf, &slog.HandlerOptions{ + Level: slog.LevelInfo, + })) + adapter := NewSplitLogger(logger) + + adapter.Info("text handler message") + + logOutput := buf.String() + assert.Contains(t, logOutput, "level=INFO") + assert.Contains(t, logOutput, "text handler message") +} + +// TestLogAdapterIsThreadSafe verifies concurrent logging safety. +func TestLogAdapterIsThreadSafe(t *testing.T) { + var buf bytes.Buffer + logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{ + Level: slog.LevelInfo, + })) + adapter := NewSplitLogger(logger) + + // Launch 10 goroutines, each logging 10 messages + const goroutines = 10 + const messagesPerGoroutine = 10 + + done := make(chan bool) + for i := 0; i < goroutines; i++ { + go func(id int) { + for j := 0; j < messagesPerGoroutine; j++ { + adapter.Info("goroutine", id, "message", j) + } + done <- true + }(i) + } + + // Wait for all goroutines to complete + for i := 0; i < goroutines; i++ { + <-done + } + + logOutput := buf.String() + + // Count the number of log entries + logLines := strings.Split(strings.TrimSpace(logOutput), "\n") + expectedLines := goroutines * messagesPerGoroutine + assert.Equal(t, expectedLines, len(logLines), "should have %d log lines", expectedLines) + + // Verify all logs are valid JSON + for i, line := range logLines { + var logEntry map[string]any + err := json.Unmarshal([]byte(line), &logEntry) + assert.NoError(t, err, "line %d should be valid JSON: %s", i, line) + } +} diff --git a/mock_client_test.go b/mock_client_test.go new file mode 100644 index 0000000..f6d681e --- /dev/null +++ b/mock_client_test.go @@ -0,0 +1,324 @@ +// Code generated by mockery; DO NOT EDIT. +// github.com/vektra/mockery +// template: testify + +package split + +import ( + "github.com/splitio/go-client/v6/splitio/client" + mock "github.com/stretchr/testify/mock" +) + +// NewMockClient creates a new instance of MockClient. It also registers a testing interface on the mock and a cleanup function to assert the mocks expectations. +// The first argument is typically a *testing.T value. +func NewMockClient(t interface { + mock.TestingT + Cleanup(func()) +}) *MockClient { + mock := &MockClient{} + mock.Mock.Test(t) + + t.Cleanup(func() { mock.AssertExpectations(t) }) + + return mock +} + +// MockClient is an autogenerated mock type for the Client type +type MockClient struct { + mock.Mock +} + +type MockClient_Expecter struct { + mock *mock.Mock +} + +func (_m *MockClient) EXPECT() *MockClient_Expecter { + return &MockClient_Expecter{mock: &_m.Mock} +} + +// BlockUntilReady provides a mock function for the type MockClient +func (_mock *MockClient) BlockUntilReady(timer int) error { + ret := _mock.Called(timer) + + if len(ret) == 0 { + panic("no return value specified for BlockUntilReady") + } + + var r0 error + if returnFunc, ok := ret.Get(0).(func(int) error); ok { + r0 = returnFunc(timer) + } else { + r0 = ret.Error(0) + } + return r0 +} + +// MockClient_BlockUntilReady_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'BlockUntilReady' +type MockClient_BlockUntilReady_Call struct { + *mock.Call +} + +// BlockUntilReady is a helper method to define mock.On call +// - timer int +func (_e *MockClient_Expecter) BlockUntilReady(timer interface{}) *MockClient_BlockUntilReady_Call { + return &MockClient_BlockUntilReady_Call{Call: _e.mock.On("BlockUntilReady", timer)} +} + +func (_c *MockClient_BlockUntilReady_Call) Run(run func(timer int)) *MockClient_BlockUntilReady_Call { + _c.Call.Run(func(args mock.Arguments) { + var arg0 int + if args[0] != nil { + arg0 = args[0].(int) + } + run( + arg0, + ) + }) + return _c +} + +func (_c *MockClient_BlockUntilReady_Call) Return(err error) *MockClient_BlockUntilReady_Call { + _c.Call.Return(err) + return _c +} + +func (_c *MockClient_BlockUntilReady_Call) RunAndReturn(run func(timer int) error) *MockClient_BlockUntilReady_Call { + _c.Call.Return(run) + return _c +} + +// Destroy provides a mock function for the type MockClient +func (_mock *MockClient) Destroy() { + _mock.Called() + return +} + +// MockClient_Destroy_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'Destroy' +type MockClient_Destroy_Call struct { + *mock.Call +} + +// Destroy is a helper method to define mock.On call +func (_e *MockClient_Expecter) Destroy() *MockClient_Destroy_Call { + return &MockClient_Destroy_Call{Call: _e.mock.On("Destroy")} +} + +func (_c *MockClient_Destroy_Call) Run(run func()) *MockClient_Destroy_Call { + _c.Call.Run(func(args mock.Arguments) { + run() + }) + return _c +} + +func (_c *MockClient_Destroy_Call) Return() *MockClient_Destroy_Call { + _c.Call.Return() + return _c +} + +func (_c *MockClient_Destroy_Call) RunAndReturn(run func()) *MockClient_Destroy_Call { + _c.Run(run) + return _c +} + +// Track provides a mock function for the type MockClient +func (_mock *MockClient) Track(key string, trafficType string, eventType string, value interface{}, properties map[string]interface{}) error { + ret := _mock.Called(key, trafficType, eventType, value, properties) + + if len(ret) == 0 { + panic("no return value specified for Track") + } + + var r0 error + if returnFunc, ok := ret.Get(0).(func(string, string, string, interface{}, map[string]interface{}) error); ok { + r0 = returnFunc(key, trafficType, eventType, value, properties) + } else { + r0 = ret.Error(0) + } + return r0 +} + +// MockClient_Track_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'Track' +type MockClient_Track_Call struct { + *mock.Call +} + +// Track is a helper method to define mock.On call +// - key string +// - trafficType string +// - eventType string +// - value interface{} +// - properties map[string]interface{} +func (_e *MockClient_Expecter) Track(key interface{}, trafficType interface{}, eventType interface{}, value interface{}, properties interface{}) *MockClient_Track_Call { + return &MockClient_Track_Call{Call: _e.mock.On("Track", key, trafficType, eventType, value, properties)} +} + +func (_c *MockClient_Track_Call) Run(run func(key string, trafficType string, eventType string, value interface{}, properties map[string]interface{})) *MockClient_Track_Call { + _c.Call.Run(func(args mock.Arguments) { + var arg0 string + if args[0] != nil { + arg0 = args[0].(string) + } + var arg1 string + if args[1] != nil { + arg1 = args[1].(string) + } + var arg2 string + if args[2] != nil { + arg2 = args[2].(string) + } + var arg3 interface{} + if args[3] != nil { + arg3 = args[3].(interface{}) + } + var arg4 map[string]interface{} + if args[4] != nil { + arg4 = args[4].(map[string]interface{}) + } + run( + arg0, + arg1, + arg2, + arg3, + arg4, + ) + }) + return _c +} + +func (_c *MockClient_Track_Call) Return(err error) *MockClient_Track_Call { + _c.Call.Return(err) + return _c +} + +func (_c *MockClient_Track_Call) RunAndReturn(run func(key string, trafficType string, eventType string, value interface{}, properties map[string]interface{}) error) *MockClient_Track_Call { + _c.Call.Return(run) + return _c +} + +// TreatmentWithConfig provides a mock function for the type MockClient +func (_mock *MockClient) TreatmentWithConfig(key interface{}, featureFlagName string, attributes map[string]interface{}) client.TreatmentResult { + ret := _mock.Called(key, featureFlagName, attributes) + + if len(ret) == 0 { + panic("no return value specified for TreatmentWithConfig") + } + + var r0 client.TreatmentResult + if returnFunc, ok := ret.Get(0).(func(interface{}, string, map[string]interface{}) client.TreatmentResult); ok { + r0 = returnFunc(key, featureFlagName, attributes) + } else { + r0 = ret.Get(0).(client.TreatmentResult) + } + return r0 +} + +// MockClient_TreatmentWithConfig_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'TreatmentWithConfig' +type MockClient_TreatmentWithConfig_Call struct { + *mock.Call +} + +// TreatmentWithConfig is a helper method to define mock.On call +// - key interface{} +// - featureFlagName string +// - attributes map[string]interface{} +func (_e *MockClient_Expecter) TreatmentWithConfig(key interface{}, featureFlagName interface{}, attributes interface{}) *MockClient_TreatmentWithConfig_Call { + return &MockClient_TreatmentWithConfig_Call{Call: _e.mock.On("TreatmentWithConfig", key, featureFlagName, attributes)} +} + +func (_c *MockClient_TreatmentWithConfig_Call) Run(run func(key interface{}, featureFlagName string, attributes map[string]interface{})) *MockClient_TreatmentWithConfig_Call { + _c.Call.Run(func(args mock.Arguments) { + var arg0 interface{} + if args[0] != nil { + arg0 = args[0].(interface{}) + } + var arg1 string + if args[1] != nil { + arg1 = args[1].(string) + } + var arg2 map[string]interface{} + if args[2] != nil { + arg2 = args[2].(map[string]interface{}) + } + run( + arg0, + arg1, + arg2, + ) + }) + return _c +} + +func (_c *MockClient_TreatmentWithConfig_Call) Return(treatmentResult client.TreatmentResult) *MockClient_TreatmentWithConfig_Call { + _c.Call.Return(treatmentResult) + return _c +} + +func (_c *MockClient_TreatmentWithConfig_Call) RunAndReturn(run func(key interface{}, featureFlagName string, attributes map[string]interface{}) client.TreatmentResult) *MockClient_TreatmentWithConfig_Call { + _c.Call.Return(run) + return _c +} + +// TreatmentsWithConfigByFlagSet provides a mock function for the type MockClient +func (_mock *MockClient) TreatmentsWithConfigByFlagSet(key interface{}, flagSet string, attributes map[string]interface{}) map[string]client.TreatmentResult { + ret := _mock.Called(key, flagSet, attributes) + + if len(ret) == 0 { + panic("no return value specified for TreatmentsWithConfigByFlagSet") + } + + var r0 map[string]client.TreatmentResult + if returnFunc, ok := ret.Get(0).(func(interface{}, string, map[string]interface{}) map[string]client.TreatmentResult); ok { + r0 = returnFunc(key, flagSet, attributes) + } else { + if ret.Get(0) != nil { + r0 = ret.Get(0).(map[string]client.TreatmentResult) + } + } + return r0 +} + +// MockClient_TreatmentsWithConfigByFlagSet_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'TreatmentsWithConfigByFlagSet' +type MockClient_TreatmentsWithConfigByFlagSet_Call struct { + *mock.Call +} + +// TreatmentsWithConfigByFlagSet is a helper method to define mock.On call +// - key interface{} +// - flagSet string +// - attributes map[string]interface{} +func (_e *MockClient_Expecter) TreatmentsWithConfigByFlagSet(key interface{}, flagSet interface{}, attributes interface{}) *MockClient_TreatmentsWithConfigByFlagSet_Call { + return &MockClient_TreatmentsWithConfigByFlagSet_Call{Call: _e.mock.On("TreatmentsWithConfigByFlagSet", key, flagSet, attributes)} +} + +func (_c *MockClient_TreatmentsWithConfigByFlagSet_Call) Run(run func(key interface{}, flagSet string, attributes map[string]interface{})) *MockClient_TreatmentsWithConfigByFlagSet_Call { + _c.Call.Run(func(args mock.Arguments) { + var arg0 interface{} + if args[0] != nil { + arg0 = args[0].(interface{}) + } + var arg1 string + if args[1] != nil { + arg1 = args[1].(string) + } + var arg2 map[string]interface{} + if args[2] != nil { + arg2 = args[2].(map[string]interface{}) + } + run( + arg0, + arg1, + arg2, + ) + }) + return _c +} + +func (_c *MockClient_TreatmentsWithConfigByFlagSet_Call) Return(stringToTreatmentResult map[string]client.TreatmentResult) *MockClient_TreatmentsWithConfigByFlagSet_Call { + _c.Call.Return(stringToTreatmentResult) + return _c +} + +func (_c *MockClient_TreatmentsWithConfigByFlagSet_Call) RunAndReturn(run func(key interface{}, flagSet string, attributes map[string]interface{}) map[string]client.TreatmentResult) *MockClient_TreatmentsWithConfigByFlagSet_Call { + _c.Call.Return(run) + return _c +} diff --git a/mock_evaluation_test.go b/mock_evaluation_test.go new file mode 100644 index 0000000..808acf9 --- /dev/null +++ b/mock_evaluation_test.go @@ -0,0 +1,574 @@ +package split + +import ( + "context" + "errors" + "log/slog" + "strings" + "testing" + "time" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/client" + "github.com/splitio/go-client/v6/splitio/conf" + "github.com/splitio/go-toolkit/v5/logging" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/mock" + "github.com/stretchr/testify/require" +) + +// ============================================================================= +// Mock Test Infrastructure +// ============================================================================= + +// createTestProvider creates a provider initialized in localhost mode, ready for +// mock client swapping. Each top-level test should call this once and share the +// provider across subtests to minimize Split SDK factory goroutine count. +// +// The returned provider's client should be swapped with swapMockClient per subtest. +func createTestProvider(t *testing.T, logBuffer *strings.Builder) *Provider { + t.Helper() + + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + var opts []Option + opts = append(opts, WithSplitConfig(cfg)) + if logBuffer != nil { + logger := slog.New(slog.NewTextHandler(logBuffer, &slog.HandlerOptions{Level: slog.LevelDebug})) + opts = append(opts, WithLogger(logger)) + } + + provider, err := New("localhost", opts...) + require.NoError(t, err) + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err) + + t.Cleanup(func() { + // Swap in a permissive mock for Destroy during shutdown + permissive := &MockClient{} + permissive.On("Destroy").Maybe() + provider.mtx.Lock() + provider.client = permissive + provider.mtx.Unlock() + + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + _ = provider.ShutdownWithContext(ctx) + }) + + return provider +} + +// swapMockClient creates a fresh MockClient for a subtest and installs it in the +// shared provider. NewMockClient(t) auto-registers AssertExpectations via t.Cleanup, +// so all expected calls are verified when the subtest completes. +func swapMockClient(t *testing.T, provider *Provider) *MockClient { + t.Helper() + mockClient := NewMockClient(t) + provider.mtx.Lock() + provider.client = mockClient + provider.mtx.Unlock() + return mockClient +} + +// createCloudTestProvider creates a test provider that reports as cloud mode +// by overriding the splitConfig.OperationMode. +func createCloudTestProvider(t *testing.T, logBuffer *strings.Builder) *Provider { + t.Helper() + provider := createTestProvider(t, logBuffer) + provider.splitConfig.OperationMode = "" + return provider +} + +// ============================================================================= +// Track: SDK Call Argument Verification (Table-Driven) +// ============================================================================= + +func TestTrackMock_SDKArguments(t *testing.T) { + provider := createTestProvider(t, nil) + + tests := []struct { + name string + targetingKey string + evalAttrs map[string]any + eventName string + detailsValue float64 + useNoMetricValue bool + wantKey string + wantTrafficType string + wantEvent string + wantValue interface{} + wantProps interface{} // mock.Anything or specific map + }{ + { + name: "default traffic type", + targetingKey: "user-123", + eventName: "checkout", + detailsValue: 42.0, + wantKey: "user-123", + wantTrafficType: "user", + wantEvent: "checkout", + wantValue: 42.0, + wantProps: mock.Anything, + }, + { + name: "custom traffic type from eval context", + targetingKey: "acct-456", + evalAttrs: map[string]any{"trafficType": "account"}, + eventName: "upgrade", + detailsValue: 99.99, + wantKey: "acct-456", + wantTrafficType: "account", + wantEvent: "upgrade", + wantValue: 99.99, + wantProps: mock.Anything, + }, + { + name: "WithoutMetricValue passes nil instead of 0", + targetingKey: "user-123", + eventName: "page_view", + detailsValue: 0, + useNoMetricValue: true, + wantKey: "user-123", + wantTrafficType: "user", + wantEvent: "page_view", + wantValue: nil, + wantProps: mock.Anything, + }, + { + name: "metric value passed through", + targetingKey: "user-123", + eventName: "purchase", + detailsValue: 149.99, + wantKey: "user-123", + wantTrafficType: "user", + wantEvent: "purchase", + wantValue: 149.99, + wantProps: mock.Anything, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + mockClient := swapMockClient(t, provider) + + mockClient.EXPECT(). + Track(tt.wantKey, tt.wantTrafficType, tt.wantEvent, tt.wantValue, tt.wantProps). + Once(). + Return(nil) + + ctx := context.Background() + if tt.useNoMetricValue { + ctx = WithoutMetricValue(ctx) + } + + evalCtx := openfeature.NewEvaluationContext(tt.targetingKey, tt.evalAttrs) + details := openfeature.NewTrackingEventDetails(tt.detailsValue) + + provider.Track(ctx, tt.eventName, evalCtx, details) + // AssertExpectations is called automatically via t.Cleanup + }) + } +} + +func TestTrackMock_PropertiesPassthrough(t *testing.T) { + provider := createTestProvider(t, nil) + mockClient := swapMockClient(t, provider) + + expectedProps := map[string]interface{}{ + "currency": "USD", + "item_count": 3, + } + + mockClient.EXPECT(). + Track("user-123", "user", "purchase", 99.0, expectedProps). + Once(). + Return(nil) + + evalCtx := openfeature.NewEvaluationContext("user-123", nil) + details := openfeature.NewTrackingEventDetails(99.0). + Add("currency", "USD"). + Add("item_count", 3) + + provider.Track(context.Background(), "purchase", evalCtx, details) +} + +// ============================================================================= +// Track: SDK Error Handling +// ============================================================================= + +func TestTrackMock_SDKError_LoggedAtError(t *testing.T) { + var logBuffer strings.Builder + provider := createTestProvider(t, &logBuffer) + mockClient := swapMockClient(t, provider) + + mockClient.EXPECT(). + Track("user-123", "user", "bad_event", 1.0, mock.Anything). + Once(). + Return(errors.New("SDK validation error: event name too long")) + + evalCtx := openfeature.NewEvaluationContext("user-123", nil) + details := openfeature.NewTrackingEventDetails(1.0) + + provider.Track(context.Background(), "bad_event", evalCtx, details) + + logOutput := logBuffer.String() + assert.Contains(t, logOutput, "tracking event failed") + assert.Contains(t, logOutput, "SDK validation error") + assert.Contains(t, logOutput, "level=ERROR") +} + +// ============================================================================= +// Track: Precondition Guard Tests (SDK NOT called) +// ============================================================================= + +func TestTrackMock_NotCalled_WhenEmptyTargetingKey(t *testing.T) { + provider := createTestProvider(t, nil) + mockClient := swapMockClient(t, provider) + + evalCtx := openfeature.NewEvaluationContext("", nil) + details := openfeature.NewTrackingEventDetails(1.0) + + provider.Track(context.Background(), "ignored_event", evalCtx, details) + + mockClient.AssertNotCalled(t, "Track", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything) +} + +func TestTrackMock_NotCalled_WhenContextCanceled(t *testing.T) { + provider := createTestProvider(t, nil) + mockClient := swapMockClient(t, provider) + + ctx, cancel := context.WithCancel(context.Background()) + cancel() + + evalCtx := openfeature.NewEvaluationContext("user-123", nil) + details := openfeature.NewTrackingEventDetails(1.0) + + provider.Track(ctx, "canceled_event", evalCtx, details) + + mockClient.AssertNotCalled(t, "Track", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything) +} + +// ============================================================================= +// ObjectEvaluation: Cloud Mode Flag Set (Table-Driven) +// ============================================================================= + +func TestObjectEvaluation_CloudMode(t *testing.T) { + configJSON := `{"primary":"#000"}` + provider := createCloudTestProvider(t, nil) + + tests := []struct { + name string + mode EvaluationMode + flagParam string + setupMock func(*MockClient) + assertResult func(*testing.T, openfeature.InterfaceResolutionDetail) + wantFlagCount int + wantNotFound bool + }{ + { + name: "default mode uses TreatmentsWithConfigByFlagSet", + flagParam: "ui-features", + setupMock: func(m *MockClient) { + m.EXPECT(). + TreatmentsWithConfigByFlagSet("key", "ui-features", mock.Anything). + Once(). + Return(map[string]client.TreatmentResult{ + "theme": {Treatment: "dark", Config: &configJSON}, + "layout": {Treatment: "grid", Config: nil}, + }) + }, + wantFlagCount: 2, + assertResult: func(t *testing.T, result openfeature.InterfaceResolutionDetail) { + t.Helper() + flagSet := result.Value.(FlagSetResult) + assert.Equal(t, "dark", flagSet["theme"].Treatment) + assert.Equal(t, map[string]any{"primary": "#000"}, flagSet["theme"].Config) + assert.Equal(t, "grid", flagSet["layout"].Treatment) + assert.Nil(t, flagSet["layout"].Config) + }, + }, + { + name: "explicit set mode uses TreatmentsWithConfigByFlagSet", + mode: EvaluationModeSet, + flagParam: "my-set", + setupMock: func(m *MockClient) { + m.EXPECT(). + TreatmentsWithConfigByFlagSet("key", "my-set", mock.Anything). + Once(). + Return(map[string]client.TreatmentResult{ + "flag_a": {Treatment: "on", Config: nil}, + }) + }, + wantFlagCount: 1, + }, + { + name: "individual mode uses TreatmentWithConfig", + mode: EvaluationModeIndividual, + flagParam: "single-flag", + setupMock: func(m *MockClient) { + m.EXPECT(). + TreatmentWithConfig("key", "single-flag", mock.Anything). + Once(). + Return(client.TreatmentResult{Treatment: "on", Config: &configJSON}) + }, + wantFlagCount: 1, + assertResult: func(t *testing.T, result openfeature.InterfaceResolutionDetail) { + t.Helper() + flagSet := result.Value.(FlagSetResult) + assert.Equal(t, "on", flagSet["single-flag"].Treatment) + assert.Equal(t, map[string]any{"primary": "#000"}, flagSet["single-flag"].Config) + }, + }, + { + name: "empty flag set returns FLAG_NOT_FOUND", + flagParam: "nonexistent-set", + setupMock: func(m *MockClient) { + m.EXPECT(). + TreatmentsWithConfigByFlagSet("key", "nonexistent-set", mock.Anything). + Once(). + Return(map[string]client.TreatmentResult{}) + }, + wantNotFound: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + mockClient := swapMockClient(t, provider) + tt.setupMock(mockClient) + + ctx := context.Background() + if tt.mode != "" { + ctx = WithEvaluationMode(ctx, tt.mode) + } + + flatCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: "key", + } + + result := provider.ObjectEvaluation(ctx, tt.flagParam, FlagSetResult{}, flatCtx) + + if tt.wantNotFound { + assert.Contains(t, result.ResolutionError.Error(), string(openfeature.FlagNotFoundCode)) + return + } + + flagSet, ok := result.Value.(FlagSetResult) + require.True(t, ok, "Value should be FlagSetResult") + assert.Len(t, flagSet, tt.wantFlagCount) + assert.Equal(t, openfeature.TargetingMatchReason, result.Reason) + + if tt.assertResult != nil { + tt.assertResult(t, result) + } + }) + } +} + +// ============================================================================= +// ObjectEvaluation: Cloud Mode JSON Config Parsing +// ============================================================================= + +func TestObjectEvaluation_CloudMode_ConfigParsesAllJSONTypes(t *testing.T) { + provider := createCloudTestProvider(t, nil) + mockClient := swapMockClient(t, provider) + + arrayConfig := `[1,2,3]` + stringConfig := `"hello"` + numberConfig := `42` + boolConfig := `true` + nullConfig := `null` + + mockClient.EXPECT(). + TreatmentsWithConfigByFlagSet("key", "json-types", mock.Anything). + Once(). + Return(map[string]client.TreatmentResult{ + "array_flag": {Treatment: "on", Config: &arrayConfig}, + "string_flag": {Treatment: "on", Config: &stringConfig}, + "number_flag": {Treatment: "on", Config: &numberConfig}, + "bool_flag": {Treatment: "on", Config: &boolConfig}, + "null_flag": {Treatment: "on", Config: &nullConfig}, + }) + + flatCtx := openfeature.FlattenedContext{openfeature.TargetingKey: "key"} + result := provider.ObjectEvaluation(context.Background(), "json-types", nil, flatCtx) + + flagSet, ok := result.Value.(FlagSetResult) + require.True(t, ok) + assert.Len(t, flagSet, 5) + + assert.Equal(t, []any{float64(1), float64(2), float64(3)}, flagSet["array_flag"].Config) + assert.Equal(t, "hello", flagSet["string_flag"].Config) + assert.Equal(t, float64(42), flagSet["number_flag"].Config) + assert.Equal(t, true, flagSet["bool_flag"].Config) + assert.Nil(t, flagSet["null_flag"].Config) +} + +// ============================================================================= +// Scalar Evaluation: Mock-Based (Table-Driven) +// ============================================================================= + +func TestScalarEvaluation_MockClient(t *testing.T) { + configJSON := `{"rollout":"gradual"}` + provider := createTestProvider(t, nil) + + tests := []struct { + name string + mockSetup func(*MockClient) + evaluate func(*Provider) interface{} + wantValue interface{} + wantMeta map[string]any // expected FlagMetadata["value"], nil if none + }{ + { + name: "BooleanEvaluation/on returns true with config", + mockSetup: func(m *MockClient) { + m.EXPECT(). + TreatmentWithConfig("user-1", "feature_x", mock.Anything). + Once(). + Return(client.TreatmentResult{Treatment: "on", Config: &configJSON}) + }, + evaluate: func(p *Provider) interface{} { + flatCtx := openfeature.FlattenedContext{openfeature.TargetingKey: "user-1"} + return p.BooleanEvaluation(context.Background(), "feature_x", false, flatCtx) + }, + wantValue: true, + wantMeta: map[string]any{"rollout": "gradual"}, + }, + { + name: "StringEvaluation/returns treatment string", + mockSetup: func(m *MockClient) { + m.EXPECT(). + TreatmentWithConfig("user-1", "color_flag", mock.Anything). + Once(). + Return(client.TreatmentResult{Treatment: "blue", Config: nil}) + }, + evaluate: func(p *Provider) interface{} { + flatCtx := openfeature.FlattenedContext{openfeature.TargetingKey: "user-1"} + return p.StringEvaluation(context.Background(), "color_flag", "red", flatCtx) + }, + wantValue: "blue", + }, + { + name: "IntEvaluation/parses treatment as int", + mockSetup: func(m *MockClient) { + m.EXPECT(). + TreatmentWithConfig("user-1", "retry_count", mock.Anything). + Once(). + Return(client.TreatmentResult{Treatment: "5", Config: nil}) + }, + evaluate: func(p *Provider) interface{} { + flatCtx := openfeature.FlattenedContext{openfeature.TargetingKey: "user-1"} + return p.IntEvaluation(context.Background(), "retry_count", 3, flatCtx) + }, + wantValue: int64(5), + }, + { + name: "FloatEvaluation/parses treatment as float", + mockSetup: func(m *MockClient) { + m.EXPECT(). + TreatmentWithConfig("user-1", "discount", mock.Anything). + Once(). + Return(client.TreatmentResult{Treatment: "0.15", Config: nil}) + }, + evaluate: func(p *Provider) interface{} { + flatCtx := openfeature.FlattenedContext{openfeature.TargetingKey: "user-1"} + return p.FloatEvaluation(context.Background(), "discount", 0.0, flatCtx) + }, + wantValue: 0.15, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + mockClient := swapMockClient(t, provider) + tt.mockSetup(mockClient) + + result := tt.evaluate(provider) + + // Assert value based on result type + switch r := result.(type) { + case openfeature.BoolResolutionDetail: + assert.Equal(t, tt.wantValue, r.Value) + assert.Equal(t, openfeature.TargetingMatchReason, r.Reason) + if tt.wantMeta != nil { + assert.Equal(t, tt.wantMeta, r.FlagMetadata["value"]) + } + case openfeature.StringResolutionDetail: + assert.Equal(t, tt.wantValue, r.Value) + assert.Equal(t, openfeature.TargetingMatchReason, r.Reason) + case openfeature.IntResolutionDetail: + assert.Equal(t, tt.wantValue, r.Value) + assert.Equal(t, openfeature.TargetingMatchReason, r.Reason) + case openfeature.FloatResolutionDetail: + assert.Equal(t, tt.wantValue, r.Value) + assert.Equal(t, openfeature.TargetingMatchReason, r.Reason) + default: + t.Fatalf("unexpected result type: %T", result) + } + }) + } +} + +// ============================================================================= +// Attributes Passthrough: Mock-Based (Table-Driven) +// ============================================================================= + +func TestEvaluation_MockClient_AttributeFiltering(t *testing.T) { + provider := createTestProvider(t, nil) + + tests := []struct { + name string + flatCtx openfeature.FlattenedContext + wantAttrs map[string]interface{} + }{ + { + name: "passes user attributes, excludes targetingKey", + flatCtx: openfeature.FlattenedContext{ + openfeature.TargetingKey: "user-1", + "email": "user@test.com", + "plan": "premium", + }, + wantAttrs: map[string]interface{}{ + "email": "user@test.com", + "plan": "premium", + }, + }, + { + name: "excludes trafficType from attributes", + flatCtx: openfeature.FlattenedContext{ + openfeature.TargetingKey: "user-1", + TrafficTypeKey: "account", + "email": "user@test.com", + }, + wantAttrs: map[string]interface{}{ + "email": "user@test.com", + }, + }, + { + name: "no extra attributes passes empty map", + flatCtx: openfeature.FlattenedContext{ + openfeature.TargetingKey: "user-1", + }, + wantAttrs: map[string]interface{}{}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + mockClient := swapMockClient(t, provider) + + mockClient.EXPECT(). + TreatmentWithConfig("user-1", "feature", tt.wantAttrs). + Once(). + Return(client.TreatmentResult{Treatment: "on", Config: nil}) + + result := provider.BooleanEvaluation(context.Background(), "feature", false, tt.flatCtx) + assert.True(t, result.Value) + }) + } +} diff --git a/options.go b/options.go new file mode 100644 index 0000000..2948ae6 --- /dev/null +++ b/options.go @@ -0,0 +1,111 @@ +package split + +import "context" + +// Private key types - MUST be unexported to prevent external collision +type evalOptionsKeyType struct{} +type trackOptionsKeyType struct{} + +// Package-level keys (unexported) +var ( + evalOptionsKey = evalOptionsKeyType{} + trackOptionsKey = trackOptionsKeyType{} +) + +// EvaluationMode controls how ObjectEvaluation interprets the flag parameter. +type EvaluationMode string + +const ( + // EvaluationModeDefault uses the provider's default behavior. + // The actual mode is determined at evaluation time based on provider mode: + // - Cloud mode: flag set evaluation (TreatmentsWithConfigByFlagSet) + // - Localhost mode: individual flag evaluation (TreatmentWithConfig) + EvaluationModeDefault EvaluationMode = "" + + // EvaluationModeSet treats the flag parameter as a flag set name. + // Uses TreatmentsWithConfigByFlagSet. + EvaluationModeSet EvaluationMode = "set" + + // EvaluationModeIndividual treats the flag parameter as a single flag name. + // Uses TreatmentWithConfig. + EvaluationModeIndividual EvaluationMode = "individual" +) + +// EvalOptions contains per-request evaluation options. +type EvalOptions struct { + // Mode controls set vs individual evaluation in ObjectEvaluation. + // Ignored in localhost mode (always individual). + Mode EvaluationMode + + // ImpressionDisabled disables impression tracking for this evaluation. + // Useful for health checks, load tests, internal tools. + // + // This mirrors Split Evaluator's per-request `impressionsDisabled` parameter. + // Split SDK-level impression modes (OPTIMIZED/DEBUG/NONE) are configured at + // initialization time via cfg.ImpressionsMode - those are NOT per-request. + // + // NOTE: Forward-looking API - not yet supported by Split Go SDK. + // Will be logged but not enforced until SDK adds per-evaluation support. + ImpressionDisabled bool +} + +// WithEvalOptions adds evaluation options to context. +func WithEvalOptions(ctx context.Context, opts EvalOptions) context.Context { + return context.WithValue(ctx, evalOptionsKey, opts) +} + +// GetEvalOptions extracts evaluation options from context. +// Returns zero value EvalOptions if not set. +func GetEvalOptions(ctx context.Context) EvalOptions { + if opts, ok := ctx.Value(evalOptionsKey).(EvalOptions); ok { + return opts + } + return EvalOptions{} +} + +// WithEvaluationMode sets only the evaluation mode. +// Uses Get-Modify-Set pattern to preserve other EvalOptions fields. +func WithEvaluationMode(ctx context.Context, mode EvaluationMode) context.Context { + opts := GetEvalOptions(ctx) + opts.Mode = mode + return WithEvalOptions(ctx, opts) +} + +// WithImpressionDisabled disables impression tracking for evaluations on this context. +// Uses Get-Modify-Set pattern to preserve other EvalOptions fields. +// NOTE: Forward-looking API - not yet enforced by Split Go SDK. +func WithImpressionDisabled(ctx context.Context) context.Context { + opts := GetEvalOptions(ctx) + opts.ImpressionDisabled = true + return WithEvalOptions(ctx, opts) +} + +// TrackOptions contains per-request tracking options. +type TrackOptions struct { + // MetricValueAbsent indicates that no metric value was provided. + // When true, the provider passes nil to Split instead of 0. + // This prevents polluting sum/average metrics with zeros. + MetricValueAbsent bool +} + +// WithTrackOptions adds tracking options to context. +func WithTrackOptions(ctx context.Context, opts TrackOptions) context.Context { + return context.WithValue(ctx, trackOptionsKey, opts) +} + +// GetTrackOptions extracts tracking options from context. +// Returns zero value TrackOptions if not set. +func GetTrackOptions(ctx context.Context) TrackOptions { + if opts, ok := ctx.Value(trackOptionsKey).(TrackOptions); ok { + return opts + } + return TrackOptions{} +} + +// WithoutMetricValue marks that no metric value should be sent. +// Uses Get-Modify-Set pattern to preserve other TrackOptions fields. +func WithoutMetricValue(ctx context.Context) context.Context { + opts := GetTrackOptions(ctx) + opts.MetricValueAbsent = true + return WithTrackOptions(ctx, opts) +} diff --git a/options_test.go b/options_test.go new file mode 100644 index 0000000..5a15779 --- /dev/null +++ b/options_test.go @@ -0,0 +1,88 @@ +package split + +import ( + "context" + "testing" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/stretchr/testify/assert" +) + +func TestWithEvalOptions(t *testing.T) { + ctx := context.Background() + + ctx = WithEvalOptions(ctx, EvalOptions{ + Mode: EvaluationModeIndividual, + ImpressionDisabled: true, + }) + + opts := GetEvalOptions(ctx) + assert.Equal(t, EvaluationModeIndividual, opts.Mode) + assert.True(t, opts.ImpressionDisabled) +} + +func TestWithEvalOptions_NotSet(t *testing.T) { + ctx := context.Background() + opts := GetEvalOptions(ctx) + + assert.Equal(t, EvaluationModeDefault, opts.Mode) + assert.False(t, opts.ImpressionDisabled) +} + +func TestWithTrackOptions_MetricValueAbsent(t *testing.T) { + ctx := context.Background() + ctx = WithoutMetricValue(ctx) + + opts := GetTrackOptions(ctx) + assert.True(t, opts.MetricValueAbsent) +} + +func TestWithEvalOptions_MultipleCalls_MergesCorrectly(t *testing.T) { + ctx := context.Background() + + // Set mode first + ctx = WithEvaluationMode(ctx, EvaluationModeIndividual) + + // Set ImpressionDisabled second - should preserve mode + ctx = WithImpressionDisabled(ctx) + + opts := GetEvalOptions(ctx) + assert.Equal(t, EvaluationModeIndividual, opts.Mode) + assert.True(t, opts.ImpressionDisabled) +} + +func TestWithTrackOptions_MultipleCalls_MergesCorrectly(t *testing.T) { + ctx := context.Background() + + ctx = WithoutMetricValue(ctx) + + opts := GetTrackOptions(ctx) + assert.True(t, opts.MetricValueAbsent) +} + +func TestContext_PassedThroughMiddlewareChain(t *testing.T) { + ctx := context.Background() + ctx = WithEvaluationMode(ctx, EvaluationModeIndividual) + ctx = WithImpressionDisabled(ctx) + ctx = WithoutMetricValue(ctx) + + evalOpts := GetEvalOptions(ctx) + trackOpts := GetTrackOptions(ctx) + + assert.Equal(t, EvaluationModeIndividual, evalOpts.Mode) + assert.True(t, evalOpts.ImpressionDisabled) + assert.True(t, trackOpts.MetricValueAbsent) +} + +func TestTrack_MetricValueAbsent_TakesPrecedence(t *testing.T) { + // Set MetricValueAbsent even though details has a non-zero value + ctx := WithoutMetricValue(context.Background()) + details := openfeature.NewTrackingEventDetails(99.99) // Has value! + + // Verify that MetricValueAbsent takes precedence in context + trackOpts := GetTrackOptions(ctx) + assert.True(t, trackOpts.MetricValueAbsent, "MetricValueAbsent should be true") + + // The value in details doesn't affect the context option + assert.Equal(t, 99.99, details.Value(), "Details still has the value") +} diff --git a/provider.go b/provider.go index 762f17a..0b1cd45 100644 --- a/provider.go +++ b/provider.go @@ -1,232 +1,246 @@ -package split_openfeature_provider_go +package split import ( - "context" - "encoding/json" - "github.com/splitio/go-client/splitio/conf" - "strconv" - - "github.com/open-feature/go-sdk/pkg/openfeature" - "github.com/splitio/go-client/splitio/client" + "fmt" + "log/slog" + "sync" + "time" + + of "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/client" + "github.com/splitio/go-client/v6/splitio/conf" + "golang.org/x/sync/singleflight" ) -type SplitProvider struct { - client client.SplitClient +// Provider implements the OpenFeature FeatureProvider interface for Split.io. +// +// # Goroutine Management and Lifecycle +// +// This provider spawns and manages goroutines with the following guarantees: +// +// 1. **Background Monitoring Goroutine** (monitorSplitUpdates) +// - Spawned: During InitWithContext after SDK is ready +// - Purpose: Monitors Split SDK for configuration changes +// - Shutdown: Gracefully terminated via close(stopMonitor) +// - Guarantee: Always terminates within the configured monitoring interval (default 30s) after stopMonitor closed +// - Tracking: monitorDone channel closed when goroutine exits +// - Safety: Panic recovery ensures monitorDone always closed +// +// 2. **Initialization Goroutine** (BlockUntilReady wrapper) +// - Spawned: During InitWithContext to monitor SDK initialization +// - Purpose: Wraps SDK's BlockUntilReady to allow context cancellation +// - Termination: Always terminates when BlockUntilReady completes (max: BlockUntilReady timeout) +// - Tracking: Tracked via sync.WaitGroup (initWg) - Add(1) before spawn, Done() on completion +// - Cleanup: ShutdownWithContext blocks on initWg.Wait() before destroying client +// - Guarantee: GUARANTEED no leak - Shutdown cannot complete until all init goroutines terminate +// - Lifecycle: Short-lived, terminates within BlockUntilReady timeout (default 10s) +// +// 3. **Shutdown Goroutine** (Destroy wrapper) +// - Spawned: During ShutdownWithContext to destroy Split SDK client +// - Purpose: Wraps SDK's Destroy() to allow context timeout +// - Termination: Terminates when Destroy() completes +// - Known Issue: In streaming mode, Destroy() can block up to 1 hour (Split SDK SSE issue) +// - Guarantee: Eventually terminates, but may outlive ShutdownWithContext's context timeout +// - Impact: Acceptable - goroutine performs cleanup and terminates, doesn't affect functionality +// +// All goroutines are properly tracked and either terminate gracefully or have documented +// termination guarantees. No unbounded goroutine leaks exist in normal operation. +type Provider struct { + client Client + initGroup singleflight.Group + monitorDone chan struct{} + logger *slog.Logger + eventStream chan of.Event + stopMonitor chan struct{} + splitConfig *conf.SplitSdkConfig + factory *client.SplitFactory + loggedOnce sync.Map // one-time log deduplication (small fixed set of keys) + initWg sync.WaitGroup + monitoringInterval time.Duration + mtx sync.RWMutex // protects client, factory, eventStream access + initMu sync.Mutex // serializes InitWithContext calls + shutdown uint32 +} + +// logOnce logs a message only once per key using sync.Map for thread-safety. +func (p *Provider) logOnce(key string, logFn func()) { + if _, loaded := p.loggedOnce.LoadOrStore(key, struct{}{}); !loaded { + logFn() + } +} + +// Config holds provider configuration. +type Config struct { + // SplitConfig is the Split SDK configuration. + // If nil, conf.Default() is used. + SplitConfig *conf.SplitSdkConfig + + // Logger is the slog.Logger used for provider and Split SDK logs. + // If nil, slog.Default() is used. + Logger *slog.Logger + + // APIKey is the Split SDK key or "localhost" for local mode. + APIKey string + + // MonitoringInterval is how often the provider checks for split definition changes. + // Default: 30 seconds. Minimum: 5 seconds. + // Lower values increase responsiveness but also CPU usage. + MonitoringInterval time.Duration +} + +// Option configures a provider Config. +type Option interface { + apply(*Config) +} + +// WithSplitConfig sets the Split SDK configuration. +func WithSplitConfig(cfg *conf.SplitSdkConfig) Option { + return withSplitConfig{cfg} +} + +type withSplitConfig struct { + cfg *conf.SplitSdkConfig +} + +func (o withSplitConfig) apply(c *Config) { + c.SplitConfig = o.cfg +} + +// WithLogger sets the logger for provider and Split SDK logs. +// The provider wraps this logger with SlogToSplitAdapter for Split SDK compatibility, +// unless SplitConfig.Logger is already set. +// This ensures unified logging across the provider, Split SDK, and OpenFeature SDK +// when the same logger is also passed to hooks.NewLoggingHook(). +func WithLogger(logger *slog.Logger) Option { + return withLogger{logger} +} + +type withLogger struct { + logger *slog.Logger +} + +func (o withLogger) apply(c *Config) { + c.Logger = o.logger +} + +// WithMonitoringInterval sets how often the provider checks for split definition changes. +// Default: 30 seconds. Minimum: 5 seconds. Values below minimum are clamped. +func WithMonitoringInterval(interval time.Duration) Option { + return withMonitoringInterval{interval} } -func NewProvider(splitClient client.SplitClient) (*SplitProvider, error) { - return &SplitProvider{ - client: splitClient, - }, nil +type withMonitoringInterval struct { + interval time.Duration } -func NewProviderSimple(apiKey string) (*SplitProvider, error) { - cfg := conf.Default() - factory, err := client.NewSplitFactory(apiKey, cfg) - if err != nil { - return nil, err - } - splitClient := factory.Client() - err = splitClient.BlockUntilReady(10) - if err != nil { - return nil, err - } - return NewProvider(*splitClient) +func (o withMonitoringInterval) apply(c *Config) { + c.MonitoringInterval = o.interval } -func (provider *SplitProvider) Metadata() openfeature.Metadata { - return openfeature.Metadata{ - Name: "Split", - } -} - -func (provider *SplitProvider) BooleanEvaluation(ctx context.Context, flag string, defaultValue bool, evalCtx openfeature.FlattenedContext) openfeature.BoolResolutionDetail { - if noTargetingKey(evalCtx) { - return openfeature.BoolResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailTargetingKeyMissing(), - } - } - evaluated := provider.evaluateTreatment(flag, evalCtx) - if noTreatment(evaluated) { - return openfeature.BoolResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailNotFound(evaluated), - } - } - var value bool - if evaluated == "true" || evaluated == "on" { - value = true - } else if evaluated == "false" || evaluated == "off" { - value = false - } else { - return openfeature.BoolResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailParseError(evaluated), - } +// New creates a Split provider with the given configuration. +// +// The apiKey parameter is required. Additional configuration can be provided +// via functional options. +// +// Example with defaults: +// +// provider, _ := split.New("YOUR_SDK_KEY") +// +// Example with custom logger: +// +// logger := slog.New(slog.NewJSONHandler(os.Stdout, nil)) +// provider, _ := split.New("YOUR_SDK_KEY", split.WithLogger(logger)) +// +// Example with custom Split SDK config: +// +// cfg := conf.Default() +// cfg.OperationMode = "localhost" +// provider, _ := split.New("localhost", split.WithSplitConfig(cfg)) +// +// Example with unified logging (provider, Split SDK, and OpenFeature SDK): +// +// logger := slog.New(slog.NewJSONHandler(os.Stdout, nil)) +// slog.SetDefault(logger) +// provider, _ := split.New("YOUR_SDK_KEY", split.WithLogger(logger)) +// openfeature.AddHooks(hooks.NewLoggingHook(false, logger)) +// +// The provider is created in NotReady state. Call Init() (or use OpenFeature's +// SetProviderAndWait) to wait for the SDK to download splits. Always call Shutdown() +// when done to clean up resources. +func New(apiKey string, opts ...Option) (*Provider, error) { + if apiKey == "" { + return nil, fmt.Errorf("split provider: apiKey is required") } - return openfeature.BoolResolutionDetail{ - Value: value, - ProviderResolutionDetail: resolutionDetailTargetingMatch(evaluated), - } -} -func (provider *SplitProvider) StringEvaluation(ctx context.Context, flag string, defaultValue string, evalCtx openfeature.FlattenedContext) openfeature.StringResolutionDetail { - if noTargetingKey(evalCtx) { - return openfeature.StringResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailTargetingKeyMissing(), - } - } - evaluated := provider.evaluateTreatment(flag, evalCtx) - if noTreatment(evaluated) { - return openfeature.StringResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailNotFound(evaluated), - } + cfg := &Config{ + APIKey: apiKey, + SplitConfig: nil, + Logger: nil, } - return openfeature.StringResolutionDetail{ - Value: evaluated, - ProviderResolutionDetail: resolutionDetailTargetingMatch(evaluated), - } -} -func (provider *SplitProvider) FloatEvaluation(ctx context.Context, flag string, defaultValue float64, evalCtx openfeature.FlattenedContext) openfeature.FloatResolutionDetail { - if noTargetingKey(evalCtx) { - return openfeature.FloatResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailTargetingKeyMissing(), - } - } - evaluated := provider.evaluateTreatment(flag, evalCtx) - if noTreatment(evaluated) { - return openfeature.FloatResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailNotFound(evaluated), - } + for _, opt := range opts { + opt.apply(cfg) } - floatEvaluated, parseErr := strconv.ParseFloat(evaluated, 64) - if parseErr != nil { - return openfeature.FloatResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailParseError(evaluated), - } - } - return openfeature.FloatResolutionDetail{ - Value: floatEvaluated, - ProviderResolutionDetail: resolutionDetailTargetingMatch(evaluated), - } -} -func (provider *SplitProvider) IntEvaluation(ctx context.Context, flag string, defaultValue int64, evalCtx openfeature.FlattenedContext) openfeature.IntResolutionDetail { - if noTargetingKey(evalCtx) { - return openfeature.IntResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailTargetingKeyMissing(), - } - } - evaluated := provider.evaluateTreatment(flag, evalCtx) - if noTreatment(evaluated) { - return openfeature.IntResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailNotFound(evaluated), - } - } - intEvaluated, parseErr := strconv.ParseInt(evaluated, 10, 64) - if parseErr != nil { - return openfeature.IntResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailParseError(evaluated), - } + if cfg.SplitConfig == nil { + cfg.SplitConfig = conf.Default() } - return openfeature.IntResolutionDetail{ - Value: intEvaluated, - ProviderResolutionDetail: resolutionDetailTargetingMatch(evaluated), + if cfg.Logger == nil { + cfg.Logger = slog.Default() } -} -func (provider *SplitProvider) ObjectEvaluation(ctx context.Context, flag string, defaultValue interface{}, evalCtx openfeature.FlattenedContext) openfeature.InterfaceResolutionDetail { - if noTargetingKey(evalCtx) { - return openfeature.InterfaceResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailTargetingKeyMissing(), - } - } - evaluated := provider.evaluateTreatment(flag, evalCtx) - if noTreatment(evaluated) { - return openfeature.InterfaceResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailNotFound(evaluated), - } - } - var data map[string]interface{} - parseErr := json.Unmarshal([]byte(evaluated), &data) - if parseErr != nil { - return openfeature.InterfaceResolutionDetail{ - Value: defaultValue, - ProviderResolutionDetail: resolutionDetailParseError(evaluated), - } - } else { - return openfeature.InterfaceResolutionDetail{ - Value: data, - ProviderResolutionDetail: resolutionDetailTargetingMatch(evaluated), - } + if cfg.SplitConfig.BlockUntilReady <= 0 { + cfg.SplitConfig.BlockUntilReady = defaultSDKTimeout } -} - -func (provider *SplitProvider) Hooks() []openfeature.Hook { - return []openfeature.Hook{} -} - -// *** Helpers *** - -func (provider *SplitProvider) evaluateTreatment(flag string, evalContext openfeature.FlattenedContext) string { - return provider.client.Treatment(evalContext[openfeature.TargetingKey], flag, nil) -} - -func noTargetingKey(evalContext openfeature.FlattenedContext) bool { - _, ok := evalContext[openfeature.TargetingKey] - return !ok -} + providerLogger := cfg.Logger.With("source", "split-provider") -func noTreatment(treatment string) bool { - return treatment == "" || treatment == "control" -} + // Apply monitoring interval defaults and minimum + monitoringInterval := cfg.MonitoringInterval + if monitoringInterval == 0 { + monitoringInterval = defaultMonitoringInterval + } else if monitoringInterval < minMonitoringInterval { + providerLogger.Warn("monitoring interval below minimum, using minimum", + "requested", monitoringInterval, + "minimum", minMonitoringInterval) + monitoringInterval = minMonitoringInterval + } -func resolutionDetailNotFound(variant string) openfeature.ProviderResolutionDetail { - return providerResolutionDetailError( - openfeature.NewFlagNotFoundResolutionError( - "Flag not found."), - openfeature.DefaultReason, - variant) -} + if cfg.SplitConfig.Logger == nil { + splitSDKLogger := cfg.Logger.With("source", "split-sdk") + cfg.SplitConfig.Logger = NewSplitLogger(splitSDKLogger) + } -func resolutionDetailParseError(variant string) openfeature.ProviderResolutionDetail { - return providerResolutionDetailError( - openfeature.NewParseErrorResolutionError("Error parsing the treatment to the given type."), - openfeature.ErrorReason, - variant) -} + factory, err := client.NewSplitFactory(cfg.APIKey, cfg.SplitConfig) + if err != nil { + return nil, fmt.Errorf("failed to create Split factory: %w", err) + } -func resolutionDetailTargetingKeyMissing() openfeature.ProviderResolutionDetail { - return providerResolutionDetailError( - openfeature.NewTargetingKeyMissingResolutionError("Targeting key is required and missing."), - openfeature.ErrorReason, - "") -} + provider := &Provider{ + client: factory.Client(), + factory: factory, + eventStream: make(chan of.Event, eventChannelBuffer), + stopMonitor: make(chan struct{}), + monitorDone: make(chan struct{}), + splitConfig: cfg.SplitConfig, + monitoringInterval: monitoringInterval, + logger: providerLogger, + } -func providerResolutionDetailError(error openfeature.ResolutionError, reason openfeature.Reason, variant string) openfeature.ProviderResolutionDetail { - return openfeature.ProviderResolutionDetail{ - ResolutionError: error, - Reason: reason, - Variant: variant, + mode := "cloud" + if provider.isLocalhostMode() { + mode = "localhost" } + providerLogger.Info("Split provider created", + "mode", mode, + "block_until_ready", cfg.SplitConfig.BlockUntilReady) + + return provider, nil } -func resolutionDetailTargetingMatch(variant string) openfeature.ProviderResolutionDetail { - return openfeature.ProviderResolutionDetail{ - Reason: openfeature.TargetingMatchReason, - Variant: variant, +// Metadata returns provider metadata with name "Split". +func (p *Provider) Metadata() of.Metadata { + return of.Metadata{ + Name: "Split", } } diff --git a/provider_test.go b/provider_test.go index 8667a3a..d8104a3 100644 --- a/provider_test.go +++ b/provider_test.go @@ -1,451 +1,403 @@ -package split_openfeature_provider_go +//nolint:dupl,gocognit // Test patterns: type-specific tests have similar structure, comprehensive tests have higher complexity +package split import ( - "github.com/open-feature/go-sdk/pkg/openfeature" - "github.com/splitio/go-client/splitio/client" - "github.com/splitio/go-client/splitio/conf" - "github.com/splitio/go-toolkit/logging" - "reflect" + "context" + "fmt" + "log/slog" "strings" + "sync" "testing" + "time" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/conf" + "github.com/splitio/go-toolkit/v5/logging" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "go.uber.org/goleak" ) +// ============================================================================= +// Test Constants +// ============================================================================= + +// Test flag names used across multiple tests +const ( + flagNonExistent = "random-non-existent-feature" + flagSomeOther = "some_other_feature" + flagMyFeature = "my_feature" + flagInt = "int_feature" + flagObj = "obj_feature" + flagUnparseable = "unparseable_feature" + flagMalformedJSON = "malformed_json_feature" + // treatmentOn and treatmentOff are defined in constants.go + treatmentUnparseable = "not-a-valid-type" // Treatment that cannot be parsed as bool/int/float + testClientName = "test_client" + testSplitFile = "testdata/split.yaml" + providerNameSplit = "Split" +) + +// ============================================================================= +// Test Main & Shared Helpers +// ============================================================================= + +// TestMain adds goroutine leak detection to all tests. +// Uses goleak to detect goroutine leaks from OUR code (external dependencies ignored). +func TestMain(m *testing.M) { + goleak.VerifyTestMain(m, + // Ignore OpenFeature SDK event executor goroutines (created per test via SetProvider) + // Use IgnoreAnyFunction because these goroutines can be in various states + // Note: Function names differ between normal and race detector builds + goleak.IgnoreAnyFunction("github.com/open-feature/go-sdk/openfeature.(*eventExecutor).startEventListener.func1.1"), + goleak.IgnoreAnyFunction("github.com/open-feature/go-sdk/openfeature.newEventExecutor.(*eventExecutor).startEventListener.func1.1"), // -race variant + goleak.IgnoreAnyFunction("github.com/open-feature/go-sdk/openfeature.(*eventExecutor).startListeningAndShutdownOld.func1"), + goleak.IgnoreAnyFunction("github.com/open-feature/go-sdk/openfeature.newEventExecutor.(*eventExecutor).startListeningAndShutdownOld.func1"), // -race variant + goleak.IgnoreAnyFunction("github.com/open-feature/go-sdk/openfeature.(*eventExecutor).triggerEvent"), + // Ignore Split SDK background goroutines (created during individual tests) + goleak.IgnoreTopFunction("github.com/splitio/go-split-commons/v8/synchronizer.(*ManagerImpl).Start.func1"), + goleak.IgnoreTopFunction("github.com/splitio/go-split-commons/v8/synchronizer.(*ManagerImpl).StartBGSync.func1"), + // Ignore standard library goroutines + goleak.IgnoreTopFunction("internal/poll.runtime_pollWait"), + goleak.IgnoreTopFunction("time.Sleep"), + ) +} + +// create sets up a provider via the global OpenFeature SDK and returns a client. +// Used for high-level OpenFeature API testing (BooleanValue, StringValue, etc.). func create(t *testing.T) *openfeature.Client { + t.Helper() cfg := conf.Default() - cfg.SplitFile = "./split.yaml" + cfg.SplitFile = testSplitFile cfg.LoggerConfig.LogLevel = logging.LevelNone - factory, err := client.NewSplitFactory("localhost", cfg) - if err != nil { - // error - t.Error("Error creating split factory") - } - splitClient := factory.Client() - err = splitClient.BlockUntilReady(10) - if err != nil { - // error timeout - t.Error("Split sdk timeout error") - } - provider, err := NewProvider(*splitClient) - if err != nil { - t.Error(err) - } - if provider == nil { - t.Error("Error creating Split Provider") - } - openfeature.SetProvider(provider) - return openfeature.NewClient("test_client") + cfg.BlockUntilReady = 10 // Must be positive + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + require.NotNil(t, provider, "Provider should not be nil") + + // Proper cleanup: Shutdown provider when test completes + t.Cleanup(func() { + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + _ = openfeature.ShutdownWithContext(ctx) + }) + + // Use context-aware SetProviderWithContextAndWait (gold standard) + ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + err = openfeature.SetProviderWithContextAndWait(ctx, provider) + require.NoError(t, err, "Failed to set provider") + + return openfeature.NewClient(testClientName) } func evaluationContext() openfeature.EvaluationContext { return openfeature.NewEvaluationContext("key", nil) } -func TestCreateSimple(t *testing.T) { - provider, err := NewProviderSimple("localhost") - if err != nil { - t.Error(err) - } - if provider == nil { - t.Error("Error creating Split Provider") - } -} - -func TestUseDefault(t *testing.T) { - ofClient := create(t) - flagName := "random-non-existent-feature" - evalCtx := evaluationContext() - - result, err := ofClient.BooleanValue(nil, flagName, false, evalCtx) - if err == nil { - t.Error("Should have returned flag not found error") - } else if !strings.Contains(err.Error(), string(openfeature.FlagNotFoundCode)) { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result == true { - t.Error("Result was true, but should have been default value of false") - } - result, err = ofClient.BooleanValue(nil, flagName, true, evalCtx) - if err == nil { - t.Error("Should have returned flag not found error") - } else if !strings.Contains(err.Error(), string(openfeature.FlagNotFoundCode)) { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result == false { - t.Error("Result was false, but should have been default value of true") - } -} - -func TestMissingTargetingKey(t *testing.T) { - ofClient := create(t) - flagName := "random-non-existent-feature" - - result, err := ofClient.BooleanValue(nil, flagName, false, openfeature.EvaluationContext{}) - if err == nil { - t.Error("Should have returned targeting key missing error") - } else if !strings.Contains(err.Error(), string(openfeature.TargetingKeyMissingCode)) { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result == true { - t.Error("Result was true, but should have been default value of false") - } -} +// ============================================================================= +// Provider Creation Tests +// ============================================================================= -func TestGetControlVariantNonExistentSplit(t *testing.T) { - ofClient := create(t) - flagName := "random-non-existent-feature" - evalCtx := evaluationContext() - - result, err := ofClient.BooleanValueDetails(nil, flagName, false, evalCtx) - if err == nil { - t.Error("Should have returned flag not found error") - } else if !strings.Contains(err.Error(), string(openfeature.FlagNotFoundCode)) { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result.Value == true { - t.Error("Result was true, but should have been default value of false") - } else if result.Variant != "control" { - t.Error("Variant should be control due to Split Go SDK functionality") - } -} - -func TestGetBooleanSplit(t *testing.T) { - ofClient := create(t) - flagName := "some_other_feature" - evalCtx := evaluationContext() - - result, err := ofClient.BooleanValue(nil, flagName, true, evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result == true { - t.Error("Result was true, but should have been false as set in split.yaml") - } -} - -func TestGetBooleanWithKeySplit(t *testing.T) { - ofClient := create(t) - flagName := "my_feature" - evalCtx := evaluationContext() - - result, err := ofClient.BooleanValue(nil, flagName, false, evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result == false { - t.Error("Result was false, but should have been true as set in split.yaml") - } - - evalCtx = openfeature.NewEvaluationContext("randomKey", nil) - result, err = ofClient.BooleanValue(nil, flagName, true, evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result == true { - t.Error("Result was true, but should have been false as set in split.yaml") - } -} - -func TestGetStringSplit(t *testing.T) { - ofClient := create(t) - flagName := "some_other_feature" - evalCtx := evaluationContext() - - result, err := ofClient.StringValue(nil, flagName, "on", evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result != "off" { - t.Errorf("Result was %s, not off as set in split.yaml", result) - } -} +func TestCreateSimple(t *testing.T) { + // Test New() with configuration + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 // Must be positive -func TestGetIntegerSplit(t *testing.T) { - ofClient := create(t) - flagName := "int_feature" - evalCtx := evaluationContext() - - result, err := ofClient.IntValue(nil, flagName, 0, evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result != 32 { - t.Errorf("Result was %d, not 32 as set in split.yaml", result) - } + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Provider creation should succeed") + assert.NotNil(t, provider, "Provider should not be nil") + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() } -func TestGetObjectSplit(t *testing.T) { - ofClient := create(t) - flagName := "obj_feature" - evalCtx := evaluationContext() - - result, err := ofClient.ObjectValue(nil, flagName, 0, evalCtx) - expectedResult := map[string]interface{}{ - "key": "value", - } - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if !reflect.DeepEqual(result, expectedResult) { - t.Error("Result was not map from key to value as set in split.yaml") - } +// TestNewErrors tests error handling in New constructor. +func TestNewErrors(t *testing.T) { + // Test with empty API key - should fail during factory creation + provider, err := New("") + assert.Error(t, err, "Empty API key should cause error") + assert.Nil(t, provider, "Provider should be nil when creation fails") + + // Test with invalid API key format - Split SDK should reject it + provider, err = New("invalid-key-format-!@#$%") + // Note: Split SDK might accept any string as API key and only fail on network calls + _ = provider + _ = err } -func TestGetFloatSplit(t *testing.T) { - ofClient := create(t) - flagName := "int_feature" - evalCtx := evaluationContext() - - result, err := ofClient.FloatValue(nil, flagName, 0, evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result != float64(32) { - t.Errorf("Result was %f, not 32 as set in split.yaml", result) - } -} +// ============================================================================= +// Metadata Tests +// ============================================================================= -func TestMetadataName(t *testing.T) { +func TestMetadataReturnsProviderName(t *testing.T) { ofClient := create(t) - if ofClient.Metadata().Name() != "test_client" { - t.Error("Client name was not set properly") - } - if openfeature.ProviderMetadata().Name != "Split" { - t.Errorf("Provider metadata name was %s, not Split", openfeature.ProviderMetadata().Name) - } + assert.Equal(t, testClientName, ofClient.Metadata().Domain(), "Client name should match") + assert.Equal(t, providerNameSplit, openfeature.ProviderMetadata().Name, "Provider name should be 'Split'") } -func TestBooleanDetails(t *testing.T) { - ofClient := create(t) - flagName := "some_other_feature" - evalCtx := evaluationContext() - - result, err := ofClient.BooleanValueDetails(nil, flagName, true, evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result.FlagKey != flagName { - t.Errorf("Flag name is %s, not %s", result.FlagKey, flagName) - } else if !strings.Contains(string(result.Reason), string(openfeature.TargetingMatchReason)) { - t.Errorf("reason is %s, not targeting match", result.Reason) - } else if result.Value == true { - t.Error("Result was true, but should have been false as in split.yaml") - } else if result.Variant != "off" { - t.Errorf("Variant should be off as in split.yaml, but was %s", result.Variant) - } else if result.ErrorCode != "" { - t.Errorf("Unexpected error in result %s", result.ErrorCode) +// ============================================================================= +// Logger Configuration Tests +// ============================================================================= + +// TestLoggerConfiguration verifies all logger configuration scenarios work correctly. +func TestLoggerConfiguration(t *testing.T) { + baseConfig := func() *conf.SplitSdkConfig { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + return cfg + } + + tests := []struct { + setup func() (provider *Provider, customSlog *slog.Logger, customSplit *customTestLogger) + name string + expectSplitLoggerType string + expectProviderUsesDefault bool + }{ + { + name: "no logger specified uses defaults", + setup: func() (*Provider, *slog.Logger, *customTestLogger) { + p, err := New("localhost") + require.NoError(t, err) + return p, nil, nil + }, + expectProviderUsesDefault: true, + expectSplitLoggerType: "adapter", + }, + { + name: "with logger option uses custom for both", + setup: func() (*Provider, *slog.Logger, *customTestLogger) { + var buf strings.Builder + customLogger := slog.New(slog.NewTextHandler(&buf, &slog.HandlerOptions{Level: slog.LevelDebug})) + p, err := New("localhost", WithLogger(customLogger)) + require.NoError(t, err) + return p, customLogger, nil + }, + expectProviderUsesDefault: false, + expectSplitLoggerType: "adapter", + }, + { + name: "split config logger only preserves custom split logger", + setup: func() (*Provider, *slog.Logger, *customTestLogger) { + customSplitLogger := &customTestLogger{logs: make([]string, 0)} + cfg := baseConfig() + cfg.Logger = customSplitLogger + p, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err) + return p, nil, customSplitLogger + }, + expectProviderUsesDefault: true, + expectSplitLoggerType: "custom", + }, + { + name: "both loggers uses each respectively", + setup: func() (*Provider, *slog.Logger, *customTestLogger) { + var buf strings.Builder + customSlogLogger := slog.New(slog.NewTextHandler(&buf, &slog.HandlerOptions{Level: slog.LevelDebug})) + customSplitLogger := &customTestLogger{logs: make([]string, 0)} + cfg := baseConfig() + cfg.Logger = customSplitLogger + p, err := New("localhost", WithLogger(customSlogLogger), WithSplitConfig(cfg)) + require.NoError(t, err) + return p, customSlogLogger, customSplitLogger + }, + expectProviderUsesDefault: false, + expectSplitLoggerType: "custom", + }, + { + name: "with logger and empty split config uses custom for both", + setup: func() (*Provider, *slog.Logger, *customTestLogger) { + var buf strings.Builder + customLogger := slog.New(slog.NewTextHandler(&buf, &slog.HandlerOptions{Level: slog.LevelDebug})) + cfg := baseConfig() + p, err := New("localhost", WithLogger(customLogger), WithSplitConfig(cfg)) + require.NoError(t, err) + return p, customLogger, nil + }, + expectProviderUsesDefault: false, + expectSplitLoggerType: "adapter", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + provider, _, customSplitLogger := tt.setup() + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + assert.NotNil(t, provider.logger, "Provider logger should be set") + assert.NotNil(t, provider.splitConfig.Logger, "Split SDK logger should be set") + + switch tt.expectSplitLoggerType { + case "adapter": + adapter, ok := provider.splitConfig.Logger.(*SlogToSplitAdapter) + require.True(t, ok, "Split SDK logger should be SlogToSplitAdapter") + assert.NotNil(t, adapter.logger, "Adapter should have a logger") + + case "custom": + assert.Equal(t, customSplitLogger, provider.splitConfig.Logger, + "Split SDK should preserve custom logger (not overwritten)") + } + }) } } -func TestIntegerDetails(t *testing.T) { - ofClient := create(t) - flagName := "int_feature" - evalCtx := evaluationContext() - - result, err := ofClient.IntValueDetails(nil, flagName, 0, evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result.FlagKey != flagName { - t.Errorf("Flag name is %s, not %s", result.FlagKey, flagName) - } else if !strings.Contains(string(result.Reason), string(openfeature.TargetingMatchReason)) { - t.Errorf("reason is %s, not targeting match", result.Reason) - } else if result.Value != int64(32) { - t.Errorf("Result was %d, but should have been 32 as in split.yaml", result.Value) - } else if result.Variant != "32" { - t.Errorf("Variant should be 32 as in split.yaml, but was %s", result.Variant) - } else if result.ErrorCode != "" { - t.Errorf("Unexpected error in result %s", result.ErrorCode) - } +// customTestLogger implements the Split SDK logging interface for testing. +// Thread-safe to handle concurrent calls from Split SDK goroutines. +type customTestLogger struct { + logs []string + mu sync.Mutex } -func TestStringDetails(t *testing.T) { - ofClient := create(t) - flagName := "some_other_feature" - evalCtx := evaluationContext() - - result, err := ofClient.StringValueDetails(nil, flagName, "blah", evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result.FlagKey != flagName { - t.Errorf("Flag name is %s, not %s", result.FlagKey, flagName) - } else if !strings.Contains(string(result.Reason), string(openfeature.TargetingMatchReason)) { - t.Errorf("reason is %s, not targeting match", result.Reason) - } else if result.Value != "off" { - t.Errorf("Result was %s, but should have been off as in split.yaml", result.Value) - } else if result.Variant != "off" { - t.Errorf("Variant should be off as in split.yaml, but was %s", result.Variant) - } else if result.ErrorCode != "" { - t.Errorf("Unexpected error in result %s", result.ErrorCode) - } +func (l *customTestLogger) Error(msg ...any) { + l.mu.Lock() + defer l.mu.Unlock() + l.logs = append(l.logs, fmt.Sprint("ERROR: ", msg)) } -func TestObjectDetails(t *testing.T) { - ofClient := create(t) - flagName := "obj_feature" - evalCtx := evaluationContext() - - result, err := ofClient.ObjectValueDetails(nil, flagName, map[string]interface{}{}, evalCtx) - expectedResult := map[string]interface{}{ - "key": "value", - } - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result.FlagKey != flagName { - t.Errorf("Flag name is %s, not %s", result.FlagKey, flagName) - } else if !strings.Contains(string(result.Reason), string(openfeature.TargetingMatchReason)) { - t.Errorf("reason is %s, not targeting match", result.Reason) - } else if !reflect.DeepEqual(result.Value, expectedResult) { - t.Error("Result was not map of key->value as in split.yaml") - } else if result.Variant != "{\"key\": \"value\"}" { - t.Errorf("Variant should be {\"key\": \"value\"} as in split.yaml, but was %s", result.Variant) - } else if result.ErrorCode != "" { - t.Errorf("Unexpected error in result %s", result.ErrorCode) - } +func (l *customTestLogger) Warning(msg ...any) { + l.mu.Lock() + defer l.mu.Unlock() + l.logs = append(l.logs, fmt.Sprint("WARN: ", msg)) } -func TestFloatDetails(t *testing.T) { - ofClient := create(t) - flagName := "int_feature" - evalCtx := evaluationContext() - - result, err := ofClient.FloatValueDetails(nil, flagName, 0, evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result.FlagKey != flagName { - t.Errorf("Flag name is %s, not %s", result.FlagKey, flagName) - } else if !strings.Contains(string(result.Reason), string(openfeature.TargetingMatchReason)) { - t.Errorf("reason is %s, not targeting match", result.Reason) - } else if result.Value != float64(32) { - t.Errorf("Result was %f, but should have been 32 as in split.yaml", result.Value) - } else if result.Variant != "32" { - t.Errorf("Variant should be 32 as in split.yaml, but was %s", result.Variant) - } else if result.ErrorCode != "" { - t.Errorf("Unexpected error in result %s", result.ErrorCode) - } - - flagName = "float_feature" - result, err = ofClient.FloatValueDetails(nil, flagName, 0, evalCtx) - if err != nil { - t.Errorf("Unexpected error occurred %s", err.Error()) - } else if result.Value != 32.5 { - t.Errorf("Result was %f, but should have been 32.5 as in split.yaml", result.Value) - } else if result.Variant != "32.5" { - t.Errorf("Variant should be 32 as in split.yaml, but was %s", result.Variant) - } else if result.ErrorCode != "" { - t.Errorf("Unexpected error in result %s", result.ErrorCode) - } +func (l *customTestLogger) Info(msg ...any) { + l.mu.Lock() + defer l.mu.Unlock() + l.logs = append(l.logs, fmt.Sprint("INFO: ", msg)) } -func TestBooleanFail(t *testing.T) { - // attempt to fetch an object treatment as a boolean. Should result in the default - ofClient := create(t) - flagName := "obj_feature" - evalCtx := evaluationContext() - - result, err := ofClient.BooleanValue(nil, flagName, false, evalCtx) - if err == nil { - t.Error("Expected exception to occur") - } else if !strings.Contains(err.Error(), string(openfeature.ParseErrorCode)) { - t.Errorf("Expected parse error, got %s", err.Error()) - } else if result != false { - t.Error("Result was true, but should have been default of false") - } - - resultDetails, err := ofClient.BooleanValueDetails(nil, flagName, false, evalCtx) - if err == nil { - t.Error("Expected exception to occur") - } else if !strings.Contains(err.Error(), string(openfeature.ParseErrorCode)) { - t.Errorf("Expected parse error, got %s", err.Error()) - } else if resultDetails.Value != false { - t.Error("Result was true, but should have been default of false") - } else if resultDetails.ErrorCode != openfeature.ParseErrorCode { - t.Errorf("Expected parse error code, got %s", resultDetails.ErrorCode) - } else if resultDetails.Reason != openfeature.ErrorReason { - t.Errorf("Expected error reason code, got %s", resultDetails.Reason) - } else if resultDetails.Variant != "{\"key\": \"value\"}" { - t.Errorf("Expected variant to be string of map, got %s", resultDetails.Variant) - } +func (l *customTestLogger) Debug(msg ...any) { + l.mu.Lock() + defer l.mu.Unlock() + l.logs = append(l.logs, fmt.Sprint("DEBUG: ", msg)) } -func TestIntegerFail(t *testing.T) { - // attempt to fetch an object treatment as an integer. Should result in the default - ofClient := create(t) - flagName := "obj_feature" - evalCtx := evaluationContext() - - result, err := ofClient.IntValue(nil, flagName, 10, evalCtx) - if err == nil { - t.Error("Expected exception to occur") - } else if !strings.Contains(err.Error(), string(openfeature.ParseErrorCode)) { - t.Errorf("Expected parse error, got %s", err.Error()) - } else if result != int64(10) { - t.Errorf("Result was %d, but should have been default of 10", result) - } - - resultDetails, err := ofClient.IntValueDetails(nil, flagName, 10, evalCtx) - if err == nil { - t.Error("Expected exception to occur") - } else if !strings.Contains(err.Error(), string(openfeature.ParseErrorCode)) { - t.Errorf("Expected parse error, got %s", err.Error()) - } else if resultDetails.Value != int64(10) { - t.Errorf("Result was %d, but should have been default of 10", resultDetails.Value) - } else if resultDetails.ErrorCode != openfeature.ParseErrorCode { - t.Errorf("Expected parse error code, got %s", resultDetails.ErrorCode) - } else if resultDetails.Reason != openfeature.ErrorReason { - t.Errorf("Expected error reason code, got %s", resultDetails.Reason) - } else if resultDetails.Variant != "{\"key\": \"value\"}" { - t.Errorf("Expected variant to be string of map, got %s", resultDetails.Variant) - } +func (l *customTestLogger) Verbose(msg ...any) { + l.mu.Lock() + defer l.mu.Unlock() + l.logs = append(l.logs, fmt.Sprint("VERBOSE: ", msg)) } -func TestFloatFail(t *testing.T) { - // attempt to fetch an object treatment as a float. Should result in the default - ofClient := create(t) - flagName := "obj_feature" - evalCtx := evaluationContext() - - result, err := ofClient.FloatValue(nil, flagName, 10, evalCtx) - if err == nil { - t.Error("Expected exception to occur") - } else if !strings.Contains(err.Error(), string(openfeature.ParseErrorCode)) { - t.Errorf("Expected parse error, got %s", err.Error()) - } else if result != float64(10) { - t.Errorf("Result was %f, but should have been default of 10", result) - } - - resultDetails, err := ofClient.FloatValueDetails(nil, flagName, 10, evalCtx) - if err == nil { - t.Error("Expected exception to occur") - } else if !strings.Contains(err.Error(), string(openfeature.ParseErrorCode)) { - t.Errorf("Expected parse error, got %s", err.Error()) - } else if resultDetails.Value != float64(10) { - t.Errorf("Result was %f, but should have been default of 10", resultDetails.Value) - } else if resultDetails.ErrorCode != openfeature.ParseErrorCode { - t.Errorf("Expected parse error code, got %s", resultDetails.ErrorCode) - } else if resultDetails.Reason != openfeature.ErrorReason { - t.Errorf("Expected error reason code, got %s", resultDetails.Reason) - } else if resultDetails.Variant != "{\"key\": \"value\"}" { - t.Errorf("Expected variant to be string of map, got %s", resultDetails.Variant) +// ============================================================================= +// splitsChanged Pure Function Tests +// ============================================================================= + +func TestSplitsChanged(t *testing.T) { + tests := []struct { + name string + old map[string]int64 + current map[string]int64 + want bool + }{ + { + name: "identical maps", + old: map[string]int64{"a": 1, "b": 2}, + current: map[string]int64{"a": 1, "b": 2}, + want: false, + }, + { + name: "both empty", + old: map[string]int64{}, + current: map[string]int64{}, + want: false, + }, + { + name: "split added", + old: map[string]int64{"a": 1}, + current: map[string]int64{"a": 1, "b": 2}, + want: true, + }, + { + name: "split removed", + old: map[string]int64{"a": 1, "b": 2}, + current: map[string]int64{"a": 1}, + want: true, + }, + { + name: "change number updated", + old: map[string]int64{"a": 1, "b": 2}, + current: map[string]int64{"a": 1, "b": 3}, + want: true, + }, + { + name: "split replaced", + old: map[string]int64{"a": 1, "b": 2}, + current: map[string]int64{"a": 1, "c": 2}, + want: true, + }, + { + name: "old nil current empty", + old: nil, + current: map[string]int64{}, + want: false, + }, + { + name: "old empty current has splits", + old: map[string]int64{}, + current: map[string]int64{"a": 1}, + want: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := splitsChanged(tt.old, tt.current) + assert.Equal(t, tt.want, got) + }) } } -func TestObjectFail(t *testing.T) { - // attempt to fetch an int as an object. Should result in the default - ofClient := create(t) - flagName := "int_feature" - evalCtx := evaluationContext() - defaultTreatment := map[string]interface{}{ - "key": "value", - } - - result, err := ofClient.ObjectValue(nil, flagName, defaultTreatment, evalCtx) - if err == nil { - t.Error("Expected exception to occur") - } else if !strings.Contains(err.Error(), string(openfeature.ParseErrorCode)) { - t.Errorf("Expected parse error, got %s", err.Error()) - } else if !reflect.DeepEqual(result, defaultTreatment) { - t.Error("Result was not default treatment") - } +// ============================================================================= +// WithMonitoringInterval Clamping Tests +// ============================================================================= - resultDetails, err := ofClient.ObjectValueDetails(nil, flagName, defaultTreatment, evalCtx) - if err == nil { - t.Error("Expected exception to occur") - } else if !strings.Contains(err.Error(), string(openfeature.ParseErrorCode)) { - t.Errorf("Expected parse error, got %s", err.Error()) - } else if !reflect.DeepEqual(resultDetails.Value, defaultTreatment) { - t.Errorf("Result was %f, but should have been default of 10", resultDetails.Value) - } else if resultDetails.ErrorCode != openfeature.ParseErrorCode { - t.Errorf("Expected parse error code, got %s", resultDetails.ErrorCode) - } else if resultDetails.Reason != openfeature.ErrorReason { - t.Errorf("Expected error reason code, got %s", resultDetails.Reason) - } else if resultDetails.Variant != "32" { - t.Errorf("Expected variant to be string of integer, got %s", resultDetails.Variant) +func TestWithMonitoringIntervalClamping(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + tests := []struct { + name string + interval time.Duration + expected time.Duration + }{ + { + name: "zero uses default", + interval: 0, + expected: 30 * time.Second, + }, + { + name: "below minimum clamped to minimum", + interval: 1 * time.Second, + expected: 5 * time.Second, + }, + { + name: "at minimum accepted", + interval: 5 * time.Second, + expected: 5 * time.Second, + }, + { + name: "above minimum accepted", + interval: 60 * time.Second, + expected: 60 * time.Second, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + var opts []Option + if tt.interval != 0 { + opts = append(opts, WithMonitoringInterval(tt.interval)) + } + provider, err := New("localhost", append(opts, WithSplitConfig(cfg))...) + require.NoError(t, err) + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + assert.Equal(t, tt.expected, provider.monitoringInterval) + }) } } diff --git a/split.yaml b/split.yaml deleted file mode 100644 index b5e3e1e..0000000 --- a/split.yaml +++ /dev/null @@ -1,14 +0,0 @@ -- my_feature: - treatment: "on" - keys: "key" - config: "{\"desc\" : \"this applies only to ON treatment\"}" -- my_feature: - treatment: "off" -- some_other_feature: - treatment: "off" -- int_feature: - treatment: "32" -- obj_feature: - treatment: "{\"key\": \"value\"}" -- float_feature: - treatment: "32.5" \ No newline at end of file diff --git a/test/advanced/README.md b/test/advanced/README.md new file mode 100644 index 0000000..63a65b7 --- /dev/null +++ b/test/advanced/README.md @@ -0,0 +1,65 @@ +# Advanced Integration Test + +Interactive test for configuration change event detection. + +## What This Tests + +**PROVIDER_CONFIGURATION_CHANGED Event Detection** - Validates that the provider correctly emits configuration change +events when flags are modified in the Split dashboard. + +This test requires manual interaction: you must modify a flag in the Split dashboard while the test is running to +trigger the event. + +All other cloud-only features (flag sets, targeting rules) are tested automatically in +the [integration test](../integration/) when `SPLIT_API_KEY` is provided. + +## Prerequisites + +- A Split account with SDK API key (server-side key) +- Any flag to modify during the test + +Set `SPLIT_API_KEY` to your Split SDK API key. + +## Provider Configuration + +The test uses a 5-second monitoring interval for faster configuration change detection: + +```go +provider, _ := split.New(apiKey, + split.WithMonitoringInterval(5*time.Second), +) +``` + +## Running + +```bash +cd test/advanced + +# Run with API key +SPLIT_API_KEY=your-key go run main.go + +# With debug logging +LOG_LEVEL=debug SPLIT_API_KEY=your-key go run main.go +``` + +## Test Flow + +1. **Initialize Provider** - Connects to Split cloud with 5-second monitoring interval +2. **Wait for Configuration Change** - Waits up to 2 minutes for `PROVIDER_CONFIGURATION_CHANGED` event + + - Modify any flag in Split dashboard to trigger the event + - Test automatically detects the change and reports success + +3. **Event Summary** - Reports counts of all provider events received + +## Notes + +- **Monitoring Interval**: The provider polls every 5 seconds (configured via `WithMonitoringInterval`). Default is 30 + seconds, minimum is 5 seconds. +- **Configuration Change Detection**: While the Split SDK receives changes via SSE near-instantly, the provider polls + for changes to emit `PROVIDER_CONFIGURATION_CHANGED` events. + +## Learn More + +- [Integration Test](../integration/) - Automated tests including flag sets and targeting (cloud mode) +- [Cloud Example](../../examples/cloud/) - Simple cloud mode example diff --git a/test/advanced/main.go b/test/advanced/main.go new file mode 100644 index 0000000..876afbb --- /dev/null +++ b/test/advanced/main.go @@ -0,0 +1,354 @@ +// Package main provides advanced tests for cloud-only Split features. +// +// This test validates: +// - Event tracking (view events in Split Data Hub) +// - PROVIDER_CONFIGURATION_CHANGED event detection +// +// Prerequisites: +// - A real Split account with SDK API key +// - For config change test: any flag to modify in the Split dashboard +// +// Run: SPLIT_API_KEY=your-key go run main.go +package main + +import ( + "context" + "fmt" + "log/slog" + "os" + "os/signal" + "strings" + "sync" + "sync/atomic" + "syscall" + "time" + + "github.com/lmittmann/tint" + "github.com/open-feature/go-sdk/openfeature" + "github.com/open-feature/go-sdk/openfeature/hooks" + + "github.com/splitio/split-openfeature-provider-go/v2" +) + +// Event counters for validation +var ( + readyCount atomic.Int32 + configChangedCount atomic.Int32 + errorCount atomic.Int32 + configChangedChan = make(chan struct{}, 10) +) + +func main() { + fmt.Println("============================================================") + fmt.Println(" Split OpenFeature Provider - Advanced Cloud Tests") + fmt.Println(" Testing: Event Tracking & Configuration Change Detection") + fmt.Println("============================================================") + fmt.Println() + + // ============================================================ + // SETUP: CONTEXT WITH TIMEOUT AND SIGNAL HANDLING + // ============================================================ + + // 5-minute timeout for interactive test + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute) + defer cancel() + + // ============================================================ + // 1. LOGGING CONFIGURATION + // ============================================================ + + logLevel := slog.LevelInfo + if level := os.Getenv("LOG_LEVEL"); level != "" { + switch level { + case "debug", "DEBUG", "trace", "TRACE": + logLevel = slog.LevelDebug + case "info", "INFO": + logLevel = slog.LevelInfo + case "warn", "WARN", "warning", "WARNING": + logLevel = slog.LevelWarn + case "error", "ERROR": + logLevel = slog.LevelError + default: + logLevel = slog.LevelInfo + } + } + + baseLogger := slog.New(tint.NewHandler(os.Stderr, &tint.Options{ + Level: logLevel, + TimeFormat: time.TimeOnly, + })) + + appLogger := baseLogger.With("source", "app") + ofLogger := baseLogger.With("source", "openfeature-sdk") + + slog.SetDefault(baseLogger) + + appLogger.Info("logging configured", "level", logLevel.String()) + + // ============================================================ + // 2. CHECK API KEY + // ============================================================ + + apiKey := os.Getenv("SPLIT_API_KEY") + if apiKey == "" { + appLogger.Error("SPLIT_API_KEY environment variable is required") + appLogger.Info("Usage: SPLIT_API_KEY=your-key go run main.go") + os.Exit(1) + } + + // ============================================================ + // 3. OPENFEATURE LOGGING HOOK + // ============================================================ + openfeature.AddHooks(hooks.NewLoggingHook(false, ofLogger)) + + // ============================================================ + // 4. EVENT HANDLERS + // ============================================================ + + readyHandler := func(details openfeature.EventDetails) { + readyCount.Add(1) + appLogger.Info("EVENT: PROVIDER_READY", + "count", readyCount.Load(), + "message", details.Message) + } + openfeature.AddHandler(openfeature.ProviderReady, &readyHandler) + + configChangeHandler := func(details openfeature.EventDetails) { + configChangedCount.Add(1) + appLogger.Info("EVENT: PROVIDER_CONFIGURATION_CHANGED", + "count", configChangedCount.Load(), + "message", details.Message) + select { + case configChangedChan <- struct{}{}: + default: + } + } + openfeature.AddHandler(openfeature.ProviderConfigChange, &configChangeHandler) + + errorHandler := func(details openfeature.EventDetails) { + errorCount.Add(1) + appLogger.Error("EVENT: PROVIDER_ERROR", + "count", errorCount.Load(), + "message", details.Message) + } + openfeature.AddHandler(openfeature.ProviderError, &errorHandler) + + appLogger.Info("event handlers registered", "handlers", 3) + + // ============================================================ + // 5. CREATE PROVIDER WITH OPTIMIZED CONFIG + // ============================================================ + + // Use optimized test configuration for faster execution + cfg := split.TestConfig() + + provider, err := split.New(apiKey, + split.WithLogger(baseLogger), + split.WithSplitConfig(cfg), + split.WithMonitoringInterval(5*time.Second), // Fast config change detection + ) + if err != nil { + appLogger.Error("failed to create provider", "error", err) + os.Exit(1) + } + + appLogger.Info("provider created", + "monitoring_interval", "5s", + "block_until_ready", cfg.BlockUntilReady) + + // ============================================================ + // 6. GRACEFUL SHUTDOWN SETUP + // ============================================================ + + var cleanupOnce sync.Once + cleanup := func() { + cleanupOnce.Do(func() { + defer func() { + if r := recover(); r != nil { + slog.Error("panic during shutdown", "panic", r) + } + }() + + fmt.Println() + fmt.Println(strings.Repeat("-", 60)) + slog.Info("initiating graceful shutdown") + + shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 10*time.Second) + defer shutdownCancel() + if err := openfeature.ShutdownWithContext(shutdownCtx); err != nil { + slog.Error("shutdown error", "error", err) + } + + slog.Info("graceful shutdown complete") + }) + } + + defer cleanup() + + // Setup interrupt handling + shutdownChan := make(chan os.Signal, 1) + done := make(chan struct{}) + signal.Notify(shutdownChan, os.Interrupt, syscall.SIGTERM) + + go func() { + select { + case sig := <-shutdownChan: + slog.Warn("interrupt signal received", "signal", sig) + signal.Stop(shutdownChan) + cancel() + case <-done: + signal.Stop(shutdownChan) + return + } + }() + + defer close(done) + + // ============================================================ + // 7. PROVIDER INITIALIZATION + // ============================================================ + + initCtx, initCancel := context.WithTimeout(ctx, 30*time.Second) + defer initCancel() + + appLogger.Info("initializing provider...") + if err := openfeature.SetProviderWithContextAndWait(initCtx, provider); err != nil { + appLogger.Error("failed to initialize provider", "error", err) + cleanup() + os.Exit(1) + } + + appLogger.Info("provider initialized successfully") + + // Create OpenFeature client for tracking + client := openfeature.NewDefaultClient() + + // ============================================================ + // TRACKING TEST + // ============================================================ + + fmt.Println() + fmt.Println("------------------------------------------------------------") + fmt.Println(">> TRACKING EVENTS (view in Split Data Hub)") + fmt.Println("------------------------------------------------------------") + + testTracking(ctx, client, appLogger) + + // ============================================================ + // CONFIGURATION CHANGE TEST + // ============================================================ + + fmt.Println() + fmt.Println("------------------------------------------------------------") + fmt.Println(">> CONFIGURATION CHANGE EVENT DETECTION") + fmt.Println("------------------------------------------------------------") + + testConfigurationChange(ctx, appLogger) + + // ============================================================ + // EVENT SUMMARY + // ============================================================ + + fmt.Println() + fmt.Println("------------------------------------------------------------") + fmt.Println(">> EVENT SUMMARY") + fmt.Println("------------------------------------------------------------") + + appLogger.Info("provider event summary", + "PROVIDER_READY", readyCount.Load(), + "PROVIDER_CONFIGURATION_CHANGED", configChangedCount.Load(), + "PROVIDER_ERROR", errorCount.Load()) + + if readyCount.Load() >= 1 { + appLogger.Info("PASS: received PROVIDER_READY event") + } else { + appLogger.Error("FAIL: did not receive PROVIDER_READY event") + } + + appLogger.Info("configuration change test completed") +} + +func testConfigurationChange(ctx context.Context, logger *slog.Logger) { + if ctx.Err() != nil { + logger.Info("skipping - context cancelled") + return + } + + // Drain any config change events that occurred before this test + for len(configChangedChan) > 0 { + <-configChangedChan + } + + logger.Info("waiting for PROVIDER_CONFIGURATION_CHANGED event...") + logger.Info("modify any flag in Split dashboard to trigger the event", "timeout", "2m") + + select { + case <-ctx.Done(): + logger.Info("context canceled") + return + case <-configChangedChan: + logger.Info("PASS: PROVIDER_CONFIGURATION_CHANGED event detected") + case <-time.After(2 * time.Minute): + logger.Warn("no configuration change detected within timeout", "timeout", "2m") + return + } +} + +// testTracking sends tracking events to Split for viewing in the console. +// Events can be viewed in Split Data Hub. +func testTracking(ctx context.Context, client *openfeature.Client, logger *slog.Logger) { + if ctx.Err() != nil { + logger.Info("skipping - context cancelled") + return + } + + logger.Info("sending tracking events to Split...") + + // Test 1: Basic event with default traffic type ("user") + evalCtx := openfeature.NewEvaluationContext("test-user-123", nil) + details := openfeature.NewTrackingEventDetails(1.0) + client.Track(ctx, "page_view", evalCtx, details) + logger.Info("sent tracking event", + "event", "page_view", + "key", "test-user-123", + "traffic_type", "user", + "value", 1.0) + + // Test 2: Event with custom traffic type + evalCtxAccount := openfeature.NewEvaluationContext("account-456", map[string]any{ + "trafficType": "account", + }) + client.Track(ctx, "subscription_created", evalCtxAccount, openfeature.NewTrackingEventDetails(99.99)) + logger.Info("sent tracking event", + "event", "subscription_created", + "key", "account-456", + "traffic_type", "account", + "value", 99.99) + + // Test 3: Event with properties + evalCtxPurchase := openfeature.NewEvaluationContext("user-789", nil) + purchaseDetails := openfeature.NewTrackingEventDetails(149.99). + Add("currency", "USD"). + Add("item_count", 3). + Add("category", "electronics"). + Add("is_first_purchase", true) + client.Track(ctx, "purchase_completed", evalCtxPurchase, purchaseDetails) + logger.Info("sent tracking event", + "event", "purchase_completed", + "key", "user-789", + "traffic_type", "user", + "value", 149.99, + "properties", "currency=USD, item_count=3, category=electronics, is_first_purchase=true") + + // Test 4: Event without value (count-only) + client.Track(ctx, "button_clicked", evalCtx, openfeature.NewTrackingEventDetails(0)) + logger.Info("sent tracking event", + "event", "button_clicked", + "key", "test-user-123", + "traffic_type", "user", + "value", 0) + + logger.Info("tracking events sent successfully", + "total_events", 4, + "note", "view events in Split Data Hub") +} diff --git a/test/cloud_flags.yaml b/test/cloud_flags.yaml new file mode 100644 index 0000000..5b64a28 --- /dev/null +++ b/test/cloud_flags.yaml @@ -0,0 +1,87 @@ +# Split OpenFeature Provider - Cloud Test Flags +# +# This file documents the flags required for cloud mode integration testing. +# Contributors can create these flags in their own Split.io account to run +# cloud mode tests with SPLIT_API_KEY. +# +# Flag Set Setup (required for ObjectEvaluation tests): +# 1. Create a flag set named "split_provider_test" in Split UI +# 2. Add flags tagged with "split-provider-test-set" to the flag set: +# - ui_theme +# - api_version +# +# Expected Test Results: +# - Localhost mode: 73 tests +# - Cloud mode: 81 tests (includes flag set tests) + +flags: + # ============================================================ + # Boolean Flags + # ============================================================ + + - name: feature_boolean_on + treatments: [ on, off ] + default: "on" + + - name: feature_boolean_off + treatments: [ on, off ] + default: "off" + + # ============================================================ + # String Flags + # ============================================================ + + - name: ui_theme + treatments: [ dark, light ] + default: "dark" + flag_set: split_provider_test # Add to flag set + config: + dark: '{"primary_color": "#1a1a2e", "secondary_color": "#16213e", "accent": "#0f3460"}' + light: '{"primary_color": "#ffffff", "secondary_color": "#f5f5f5", "accent": "#e8e8e8"}' + targeting: + - when: variant = "two" + serve: "light" + + - name: api_version + treatments: [ v1, v2 ] + default: "v2" + flag_set: split_provider_test # Add to flag set + targeting: + - when: variant = "two" + serve: "v1" + + - name: homepage_variant + treatments: [ variant_a, variant_b ] + default: "variant_b" + + # ============================================================ + # Integer Flags + # ============================================================ + + - name: max_retries + treatments: [ "3", "5" ] + default: "5" + + - name: page_size + treatments: [ "25", "50" ] + default: "50" + + - name: timeout_seconds + treatments: [ "15", "30" ] + default: "30" + + # ============================================================ + # Float Flags + # ============================================================ + + - name: discount_rate + treatments: [ "0.10", "0.15" ] + default: "0.15" + + - name: cache_hit_ratio + treatments: [ "0.75", "0.85" ] + default: "0.85" + + - name: sampling_rate + treatments: [ "0.01", "0.05" ] + default: "0.01" diff --git a/test/integration/README.md b/test/integration/README.md new file mode 100644 index 0000000..2550150 --- /dev/null +++ b/test/integration/README.md @@ -0,0 +1,75 @@ +# Integration Test + +Comprehensive integration test validating all provider features with automated assertions. + +## What This Tests + +- Custom Split SDK configuration with flexible mode (localhost or cloud) +- Structured logging with slog and colored output via tint +- Event handling (PROVIDER_READY, PROVIDER_ERROR, PROVIDER_CONFIGURATION_CHANGED) +- Graceful shutdown with context cancellation and interrupt handling +- All evaluation types (boolean, string, int, float, object) +- Evaluation details (variant, reason, flag key) +- Flag metadata (configurations attached to flags) +- Flag set evaluation (cloud mode only) +- Targeting with user attributes +- Context cancellation and timeout handling +- Direct Split SDK access (Track, Treatments) +- Concurrent evaluations (100 goroutines x 10 evaluations) +- Provider lifecycle (init, shutdown, named providers) + +**Test Coverage:** + +- Localhost mode: 85 tests +- Cloud mode: 94 tests (includes flag set tests) + +## File Structure + +| File | Purpose | +|------------------|------------------------------------------------------------------------| +| `main.go` | Entry point, setup, and test orchestration | +| `results.go` | Test result tracking with atomic counters | +| `evaluations.go` | Flag evaluation tests (boolean, string, int, float, object, targeting) | +| `lifecycle.go` | Provider lifecycle tests (init, shutdown, named providers, timeouts) | +| `sdk.go` | SDK access, concurrent evaluations, metrics, and health tests | + +## Running + +```bash +cd test/integration + +# Localhost mode (recommended - no API key needed) +go run . + +# With debug logging +LOG_LEVEL=debug go run . + +# Cloud mode (requires flags created per test/cloud_flags.yaml) +SPLIT_API_KEY=your-key go run . +``` + +## Test Modes + +### Localhost Mode (default) + +Uses `split.yaml` file with test flags. Runs all tests except flag set evaluation (85 tests). + +### Cloud Mode (with SPLIT_API_KEY) + +Connects to Split cloud. Runs flag set evaluation tests in addition to all other tests (94 tests total). +Requires flags created per `test/cloud_flags.yaml`. + +## Exit Codes + +- `0`: All tests passed +- `1`: One or more tests failed +- `2`: Timeout or fatal error + +Timeout: 5 minutes. + +## Learn More + +- [Advanced Test](../advanced/) - Configuration change event detection (requires manual flag modification) +- [Split OpenFeature Go Provider Documentation](../../README.md) +- [OpenFeature Go SDK](https://openfeature.dev/docs/reference/sdks/server/go) +- [Split Go SDK](https://github.com/splitio/go-client) diff --git a/test/integration/evaluations.go b/test/integration/evaluations.go new file mode 100644 index 0000000..4c07f57 --- /dev/null +++ b/test/integration/evaluations.go @@ -0,0 +1,611 @@ +// evaluations.go contains flag evaluation tests for all types. +// Tests cover boolean, string, int, float, and object evaluations, +// as well as evaluation details, flag metadata, flag sets, targeting, +// context cancellation, and error handling. +package main + +import ( + "context" + "fmt" + "log/slog" + "time" + + "github.com/open-feature/go-sdk/openfeature" + + "github.com/splitio/split-openfeature-provider-go/v2" +) + +// testBooleanEvaluations tests boolean flag evaluations (on/off) +func testBooleanEvaluations(ctx context.Context, client *openfeature.Client) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + tests := []struct { + flag string + expected bool + }{ + {"feature_boolean_on", true}, + {"feature_boolean_off", false}, + } + + for _, tt := range tests { + value, err := client.BooleanValue(ctx, tt.flag, !tt.expected, evalCtx) + if err != nil { + results.Fail(fmt.Sprintf("Boolean(%s)", tt.flag), err.Error()) + continue + } + + if value != tt.expected { + results.Fail(fmt.Sprintf("Boolean(%s)", tt.flag), + fmt.Sprintf("expected %v, got %v", tt.expected, value)) + } else { + results.Pass(fmt.Sprintf("Boolean(%s)", tt.flag)) + } + } +} + +// testStringEvaluations tests string flag evaluations +func testStringEvaluations(ctx context.Context, client *openfeature.Client) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + tests := []struct { + flag string + expected string + }{ + {"ui_theme", "dark"}, + {"api_version", "v2"}, + {"homepage_variant", "variant_b"}, + } + + for _, tt := range tests { + value, err := client.StringValue(ctx, tt.flag, "", evalCtx) + if err != nil { + results.Fail(fmt.Sprintf("String(%s)", tt.flag), err.Error()) + continue + } + + if value != tt.expected { + results.Fail(fmt.Sprintf("String(%s)", tt.flag), + fmt.Sprintf("expected %s, got %s", tt.expected, value)) + } else { + results.Pass(fmt.Sprintf("String(%s)", tt.flag)) + } + } +} + +// testIntEvaluations tests integer flag evaluations +func testIntEvaluations(ctx context.Context, client *openfeature.Client) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + tests := []struct { + flag string + expected int64 + }{ + {"max_retries", 5}, + {"page_size", 50}, + {"timeout_seconds", 30}, + } + + for _, tt := range tests { + value, err := client.IntValue(ctx, tt.flag, 0, evalCtx) + if err != nil { + results.Fail(fmt.Sprintf("Int(%s)", tt.flag), err.Error()) + continue + } + + if value != tt.expected { + results.Fail(fmt.Sprintf("Int(%s)", tt.flag), + fmt.Sprintf("expected %d, got %d", tt.expected, value)) + } else { + results.Pass(fmt.Sprintf("Int(%s)", tt.flag)) + } + } +} + +// testFloatEvaluations tests float flag evaluations +func testFloatEvaluations(ctx context.Context, client *openfeature.Client) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + tests := []struct { + flag string + expected float64 + }{ + {"discount_rate", 0.15}, + {"cache_hit_ratio", 0.85}, + {"sampling_rate", 0.01}, + } + + for _, tt := range tests { + value, err := client.FloatValue(ctx, tt.flag, 0.0, evalCtx) + if err != nil { + results.Fail(fmt.Sprintf("Float(%s)", tt.flag), err.Error()) + continue + } + + if value != tt.expected { + results.Fail(fmt.Sprintf("Float(%s)", tt.flag), + fmt.Sprintf("expected %.4f, got %.4f", tt.expected, value)) + } else { + results.Pass(fmt.Sprintf("Float(%s)", tt.flag)) + } + } +} + +// testObjectEvaluations tests object flag evaluations (localhost mode only) +func testObjectEvaluations(ctx context.Context, client *openfeature.Client) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + // Test 1: Single flag evaluation (localhost mode) + // Returns: FlagSetResult{"premium_features": FlagResult{Treatment: "on", Config: {...}}} + value, err := client.ObjectValue(ctx, "premium_features", split.FlagSetResult{}, evalCtx) + if err != nil { + results.Fail("Object(premium_features)", err.Error()) + } else { + // Type-assert to FlagSetResult + flags, ok := value.(split.FlagSetResult) + if !ok { + results.Fail("Object(premium_features)", fmt.Sprintf("expected FlagSetResult, got %T", value)) + return + } + + // Check structure: should have flag name as key + flagData, ok := flags["premium_features"] + if !ok { + results.Fail("Object(premium_features)", "flag data not found") + return + } + + slog.Info("object evaluation result", + "flag", "premium_features", + "treatment", flagData.Treatment, + "has_config", flagData.Config != nil) + + results.Pass("Object(premium_features)") + } + + // Test 2: Object with configuration + // This demonstrates accessing JSON config data attached to treatments + value, err = client.ObjectValue(ctx, "feature_config", split.FlagSetResult{}, evalCtx) + if err != nil { + results.Fail("Object(feature_config)", err.Error()) + } else { + flags, ok := value.(split.FlagSetResult) + if !ok { + results.Fail("Object(feature_config)", fmt.Sprintf("expected FlagSetResult, got %T", value)) + return + } + + flagData, ok := flags["feature_config"] + if !ok { + results.Fail("Object(feature_config)", "flag data not found") + return + } + + // Check if config is present and valid + if config, ok := flagData.Config.(map[string]any); ok { + slog.Info("config data received", + "flag", "feature_config", + "config_keys", len(config)) + results.Pass("Object(feature_config)") + } else { + results.Pass("Object(feature_config) - no config") + } + } +} + +// testEvaluationDetails tests evaluation details (variant, reason, flagKey) +func testEvaluationDetails(ctx context.Context, client *openfeature.Client) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + details, err := client.BooleanValueDetails(ctx, "feature_boolean_on", false, evalCtx) + if err != nil { + results.Fail("BooleanDetails(variant)", err.Error()) + return + } + + if details.Variant == "" { + results.Fail("BooleanDetails(variant)", "variant is empty") + } else { + results.Pass("BooleanDetails(variant)") + } + + if details.Reason == "" { + results.Fail("BooleanDetails(reason)", "reason is empty") + } else { + results.Pass("BooleanDetails(reason)") + } + + if details.FlagKey != "feature_boolean_on" { + results.Fail("BooleanDetails(flagKey)", fmt.Sprintf("expected feature_boolean_on, got %s", details.FlagKey)) + } else { + results.Pass("BooleanDetails(flagKey)") + } +} + +// testFlagMetadata tests flag metadata (configurations attached to flags) +func testFlagMetadata(ctx context.Context, client *openfeature.Client) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + stringDetails, err := client.StringValueDetails(ctx, "ui_theme", "light", evalCtx) + if err != nil { + results.Fail("FlagMetadata(string)", err.Error()) + return + } + + if stringDetails.FlagMetadata != nil && len(stringDetails.FlagMetadata) > 0 { + slog.Info("flag metadata in StringDetails", + "flag", "ui_theme", + "treatment", stringDetails.Value, + "metadata_keys", len(stringDetails.FlagMetadata)) + + if configValue, ok := stringDetails.FlagMetadata["value"]; ok { + if configMap, ok := configValue.(map[string]any); ok { + if primaryColor, ok := configMap["primary_color"]; ok { + slog.Info("config field accessible", "primary_color", primaryColor) + results.Pass("FlagMetadata(string)") + } else { + results.Pass("FlagMetadata(string) - no primary_color") + } + } else { + results.Pass("FlagMetadata(string) - non-object config") + } + } else { + results.Pass("FlagMetadata(string) - no config") + } + } else { + results.Pass("FlagMetadata(string) - no metadata") + } + + boolDetails, err := client.BooleanValueDetails(ctx, "feature_boolean_on", false, evalCtx) + if err != nil { + results.Fail("FlagMetadata(boolean)", err.Error()) + return + } + + if boolDetails.FlagMetadata != nil { + slog.Info("flag metadata in BooleanDetails", + "flag", "feature_boolean_on", + "treatment", boolDetails.Variant, + "has_metadata", len(boolDetails.FlagMetadata) > 0) + results.Pass("FlagMetadata(boolean)") + } else { + results.Pass("FlagMetadata(boolean) - no metadata") + } + + intDetails, err := client.IntValueDetails(ctx, "max_retries", 3, evalCtx) + if err != nil { + results.Fail("FlagMetadata(int)", err.Error()) + return + } + + if intDetails.FlagMetadata != nil { + slog.Info("flag metadata in IntDetails", + "flag", "max_retries", + "value", intDetails.Value, + "has_metadata", len(intDetails.FlagMetadata) > 0) + results.Pass("FlagMetadata(int)") + } else { + results.Pass("FlagMetadata(int) - no metadata") + } + + floatDetails, err := client.FloatValueDetails(ctx, "timeout_seconds", 5.0, evalCtx) + if err != nil { + results.Fail("FlagMetadata(float)", err.Error()) + return + } + + if floatDetails.FlagMetadata != nil { + slog.Info("flag metadata in FloatDetails", + "flag", "timeout_seconds", + "value", floatDetails.Value, + "has_metadata", len(floatDetails.FlagMetadata) > 0) + results.Pass("FlagMetadata(float)") + } else { + results.Pass("FlagMetadata(float) - no metadata") + } + + details, err := client.StringValueDetails(ctx, "api_version", "v1", evalCtx) + if err != nil { + results.Fail("FlagMetadata(wrapped)", err.Error()) + return + } + + if details.FlagMetadata != nil { + if wrappedValue, ok := details.FlagMetadata["value"]; ok { + slog.Info("config accessible via 'value' key", + "flag", "api_version", + "value", wrappedValue) + results.Pass("FlagMetadata(wrapped)") + } else { + results.Pass("FlagMetadata(wrapped) - no value key") + } + } else { + results.Pass("FlagMetadata(wrapped) - no metadata") + } +} + +// testFlagSetEvaluation tests flag set evaluation (cloud mode only) +func testFlagSetEvaluation(ctx context.Context, client *openfeature.Client) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + // ============================================================ + // Test 1: Basic flag set evaluation + // ============================================================ + flagSet := "split_provider_test" + slog.Info("evaluating flag set", "flag_set", flagSet) + + result, err := client.ObjectValue(ctx, flagSet, split.FlagSetResult{}, evalCtx) + if err != nil { + results.Fail("FlagSet(evaluation)", err.Error()) + return + } + + flags, ok := result.(split.FlagSetResult) + if !ok { + results.Fail("FlagSet(type)", fmt.Sprintf("expected FlagSetResult, got %T", result)) + return + } + + // Should have at least 2 flags (ui_theme and api_version) + if len(flags) < 2 { + results.Fail("FlagSet(count)", fmt.Sprintf("expected at least 2 flags, got %d", len(flags))) + return + } + results.Pass(fmt.Sprintf("FlagSet(count=%d)", len(flags))) + + // ============================================================ + // Test 2: Verify flag structure (Treatment and Config fields) + // ============================================================ + if uiTheme, ok := flags["ui_theme"]; ok { + slog.Info("flag in set", "flag", "ui_theme", "treatment", uiTheme.Treatment) + results.Pass("FlagSet(ui_theme_treatment)") + // Config field always exists in FlagResult struct + results.Pass("FlagSet(ui_theme_config)") + } else { + results.Fail("FlagSet(ui_theme)", "flag not found in set") + } + + // ============================================================ + // Test 3: Verify second flag in set + // ============================================================ + if apiVersion, ok := flags["api_version"]; ok { + slog.Info("flag in set", "flag", "api_version", "treatment", apiVersion.Treatment) + results.Pass("FlagSet(api_version)") + } else { + results.Fail("FlagSet(api_version)", "flag not found in set") + } + + // ============================================================ + // Test 4: Flag set with targeting attributes + // ============================================================ + evalCtxWithAttr := openfeature.NewEvaluationContext("test-user-2", map[string]any{ + "variant": "two", + }) + + result2, err := client.ObjectValue(ctx, flagSet, split.FlagSetResult{}, evalCtxWithAttr) + if err != nil { + results.Fail("FlagSet(targeting)", err.Error()) + return + } + + flags2, ok := result2.(split.FlagSetResult) + if !ok { + results.Fail("FlagSet(targeting_type)", fmt.Sprintf("expected FlagSetResult, got %T", result2)) + return + } + + // Verify ui_theme returns "light" when variant=two (targeting rule) + if uiTheme, ok := flags2["ui_theme"]; ok { + if uiTheme.Treatment == "light" { + results.Pass("FlagSet(targeting_ui_theme)") + } else { + results.Fail("FlagSet(targeting_ui_theme)", fmt.Sprintf("expected light, got %s", uiTheme.Treatment)) + } + } else { + results.Fail("FlagSet(targeting_ui_theme)", "flag not found") + } + + // Verify api_version returns "v1" when variant=two (targeting rule) + if apiVersion, ok := flags2["api_version"]; ok { + if apiVersion.Treatment == "v1" { + results.Pass("FlagSet(targeting_api_version)") + } else { + results.Fail("FlagSet(targeting_api_version)", fmt.Sprintf("expected v1, got %s", apiVersion.Treatment)) + } + } else { + results.Fail("FlagSet(targeting_api_version)", "flag not found") + } + + // ============================================================ + // Test 5: Non-existent flag set returns default + // ============================================================ + result3, err := client.ObjectValue(ctx, "non_existent_flag_set", split.FlagSetResult{}, evalCtx) + if err != nil { + // Error is acceptable for non-existent flag set + results.Pass("FlagSet(non_existent_error)") + } else { + // Should return default value (empty FlagSetResult) + if resultFlags, ok := result3.(split.FlagSetResult); ok { + if len(resultFlags) == 0 { + results.Pass("FlagSet(non_existent_empty)") + } else { + results.Fail("FlagSet(non_existent)", "unexpected non-empty result") + } + } else { + results.Fail("FlagSet(non_existent)", fmt.Sprintf("expected FlagSetResult, got %T", result3)) + } + } + + // ============================================================ + // Test 6: ObjectValueDetails for flag set + // ============================================================ + details, err := client.ObjectValueDetails(ctx, flagSet, split.FlagSetResult{}, evalCtx) + if err != nil { + results.Fail("FlagSet(details)", err.Error()) + return + } + + // Verify reason is TARGETING_MATCH + if details.Reason == openfeature.TargetingMatchReason { + results.Pass("FlagSet(details_reason)") + } else { + results.Fail("FlagSet(details_reason)", fmt.Sprintf("expected TARGETING_MATCH, got %s", details.Reason)) + } + + // Verify variant is the flag set name + if details.Variant == flagSet { + results.Pass("FlagSet(details_variant)") + } else { + results.Fail("FlagSet(details_variant)", fmt.Sprintf("expected %s, got %s", flagSet, details.Variant)) + } + + // Verify value is a FlagSetResult with flags + if detailsValue, ok := details.Value.(split.FlagSetResult); ok { + if len(detailsValue) >= 2 { + results.Pass("FlagSet(details_value)") + } else { + results.Fail("FlagSet(details_value)", fmt.Sprintf("expected at least 2 flags, got %d", len(detailsValue))) + } + } else { + results.Fail("FlagSet(details_value)", fmt.Sprintf("expected FlagSetResult, got %T", details.Value)) + } +} + +// testAttributeTargeting tests targeting with evaluation context attributes +func testAttributeTargeting(ctx context.Context, client *openfeature.Client) { + evalCtx1 := openfeature.NewEvaluationContext("test-user", map[string]any{ + "email": "vip@example.com", + "plan": "enterprise", + "age": int64(30), + }) + + value, err := client.StringValue(ctx, "ui_theme", "light", evalCtx1) + if err != nil { + results.Fail("Attributes(with_attrs)", err.Error()) + } else if value != "dark" { + results.Fail("Attributes(with_attrs)", fmt.Sprintf("expected dark, got %s", value)) + } else { + results.Pass("Attributes(with_attrs)") + } + + evalCtx2 := openfeature.NewEvaluationContext("another-user", map[string]any{ + "email": "user@example.com", + "plan": "basic", + "premium": false, + }) + + value, err = client.StringValue(ctx, "api_version", "v1", evalCtx2) + if err != nil { + results.Fail("Attributes(different_user)", err.Error()) + } else if value != "v2" { + results.Fail("Attributes(different_user)", fmt.Sprintf("expected v2, got %s", value)) + } else { + results.Pass("Attributes(different_user)") + } +} + +// testContextCancellation tests behavior when context is cancelled +func testContextCancellation(client *openfeature.Client) { + + ctx, cancel := context.WithTimeout(context.Background(), 1*time.Nanosecond) + defer cancel() + + time.Sleep(10 * time.Millisecond) + + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + value, err := client.BooleanValue(ctx, "feature_boolean_on", false, evalCtx) + + if err == nil { + results.Fail("Context(cancellation)", "expected error for cancelled context") + } else if value != false { + results.Fail("Context(cancellation)", "should return default value on cancellation") + } else { + results.Pass("Context(cancellation)") + } +} + +// testErrorHandling tests error handling for invalid inputs +func testErrorHandling(ctx context.Context, client *openfeature.Client) { + evalCtx := openfeature.NewEvaluationContext("", nil) + value, err := client.BooleanValue(ctx, "feature_boolean_on", false, evalCtx) + + if err == nil { + results.Fail("Error(missing_key)", "expected error for empty targeting key") + } else if value != false { + results.Fail("Error(missing_key)", "should return default on error") + } else { + results.Pass("Error(missing_key)") + } + + evalCtx2 := openfeature.NewEvaluationContext("test-user", nil) + value, err = client.BooleanValue(ctx, "non_existent_flag", true, evalCtx2) + + if err == nil { + results.Fail("Error(non_existent)", "expected error for non-existent flag") + } else if value != true { + results.Fail("Error(non_existent)", "should return default for non-existent flag") + } else { + results.Pass("Error(non_existent)") + } +} + +// testObjectEvaluationMode tests EvaluationMode context options in ObjectEvaluation. +// In localhost mode, EvaluationModeSet is ignored (always uses individual). +// In cloud mode, EvaluationModeIndividual forces single flag evaluation. +// +// Key insight: flags in a flag set also exist as individual flags in Split, +// so "ui_theme" works for both individual and flag set evaluation. +func testObjectEvaluationMode(ctx context.Context, provider *split.Provider, isLocalhostMode bool) { + evalCtx := openfeature.FlattenedContext{ + openfeature.TargetingKey: "test-user", + } + + // Use "ui_theme" for individual evaluation (exists in both localhost split.yaml and cloud dashboard). + // Use "split_provider_test" for flag set evaluation in cloud (contains ui_theme and other flags). + individualFlag := "ui_theme" + flagSet := "split_provider_test" + + // Test 1: EvaluationModeIndividual should evaluate a single flag in both modes + individualCtx := split.WithEvaluationMode(ctx, split.EvaluationModeIndividual) + result := provider.ObjectEvaluation(individualCtx, individualFlag, nil, evalCtx) + + flags, ok := result.Value.(split.FlagSetResult) + if !ok { + results.Fail("ObjectMode(individual)", fmt.Sprintf("expected FlagSetResult, got %T", result.Value)) + } else if len(flags) != 1 { + results.Fail("ObjectMode(individual)", fmt.Sprintf("expected 1 flag, got %d", len(flags))) + } else { + results.Pass("ObjectMode(individual)") + } + + // Test 2: EvaluationModeSet in localhost should be ignored (still evaluates single flag) + if isLocalhostMode { + setCtx := split.WithEvaluationMode(ctx, split.EvaluationModeSet) + result = provider.ObjectEvaluation(setCtx, individualFlag, nil, evalCtx) + + flags, ok = result.Value.(split.FlagSetResult) + if !ok { + results.Fail("ObjectMode(set_ignored_localhost)", fmt.Sprintf("expected FlagSetResult, got %T", result.Value)) + } else if len(flags) != 1 { + results.Fail("ObjectMode(set_ignored_localhost)", fmt.Sprintf("expected 1 flag (set mode ignored), got %d", len(flags))) + } else { + results.Pass("ObjectMode(set_ignored_localhost)") + } + } + + // Test 3: Default mode should work + // Localhost default: evaluates individual flag + // Cloud default: evaluates flag set + defaultKey := individualFlag + if !isLocalhostMode { + defaultKey = flagSet + } + result = provider.ObjectEvaluation(ctx, defaultKey, nil, evalCtx) + flags, ok = result.Value.(split.FlagSetResult) + if !ok { + results.Fail("ObjectMode(default)", fmt.Sprintf("expected FlagSetResult, got %T", result.Value)) + } else if len(flags) == 0 { + results.Fail("ObjectMode(default)", "expected at least 1 flag") + } else { + results.Pass("ObjectMode(default)") + } +} diff --git a/test/integration/lifecycle.go b/test/integration/lifecycle.go new file mode 100644 index 0000000..2f48a0a --- /dev/null +++ b/test/integration/lifecycle.go @@ -0,0 +1,538 @@ +// lifecycle.go contains provider lifecycle tests. +// Tests cover initialization, shutdown, named providers, concurrent init, +// timeout handling, status atomicity, and idempotent operations. +package main + +import ( + "context" + "fmt" + "log/slog" + "strings" + "sync" + "time" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/conf" + + "github.com/splitio/split-openfeature-provider-go/v2" +) + +// testInitAfterShutdown tests that init fails after shutdown +func testInitAfterShutdown(apiKey string, logger *slog.Logger, cfg *conf.SplitSdkConfig) { + + testProvider, err := split.New(apiKey, split.WithLogger(logger), split.WithSplitConfig(cfg)) + if err != nil { + results.Fail("InitAfterShutdown(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + + initCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + if err := testProvider.InitWithContext(initCtx, evalCtx); err != nil { + results.Fail("InitAfterShutdown(init)", fmt.Sprintf("init failed: %v", err)) + testProvider.Shutdown() + return + } + + shutdownCtx, cancel2 := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel2() + + if err := testProvider.ShutdownWithContext(shutdownCtx); err != nil { + // In cloud mode with SSE streaming, the Split SDK has a known hang bug + // that can cause shutdown to timeout. Accept this as valid for cloud mode. + if apiKey != "localhost" && strings.Contains(err.Error(), "context deadline exceeded") { + // Continue with test - shutdown timeout is acceptable in cloud mode + } else { + results.Fail("InitAfterShutdown(shutdown)", fmt.Sprintf("shutdown failed: %v", err)) + return + } + } + + initCtx2, cancel3 := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel3() + + err = testProvider.InitWithContext(initCtx2, evalCtx) + + if err == nil { + results.Fail("InitAfterShutdown", "expected error, got nil") + } else if !strings.Contains(err.Error(), "cannot initialize provider after shutdown") { + results.Fail("InitAfterShutdown", fmt.Sprintf("wrong error message: %v", err)) + } else { + results.Pass("InitAfterShutdown") + } +} + +// testNamedProvider tests creating and using a named provider +func testNamedProvider(ctx context.Context, apiKey string, logger *slog.Logger, cfg *conf.SplitSdkConfig) { + // Create a named provider + namedProvider, err := split.New(apiKey, split.WithLogger(logger), split.WithSplitConfig(cfg)) + if err != nil { + results.Fail("NamedProvider(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + defer namedProvider.Shutdown() + + initCtx, cancel := context.WithTimeout(ctx, 15*time.Second) + defer cancel() + + if err := openfeature.SetNamedProviderWithContextAndWait(initCtx, "test-split", namedProvider); err != nil { + results.Fail("NamedProvider(init)", fmt.Sprintf("failed to initialize: %v", err)) + return + } + results.Pass("NamedProvider(init)") + + namedClient := openfeature.NewClient("test-split") + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + // Test evaluation with named client + value, err := namedClient.BooleanValue(ctx, "feature_boolean_on", false, evalCtx) + if err != nil { + results.Fail("NamedProvider(evaluation)", fmt.Sprintf("evaluation failed: %v", err)) + return + } + + if value != true { + results.Fail("NamedProvider(value)", fmt.Sprintf("expected true, got %v", value)) + } else { + results.Pass("NamedProvider(evaluation)") + } + + // Cleanup happens via defer namedProvider.Shutdown() + results.Pass("NamedProvider(cleanup)") +} + +// testConcurrentInit tests concurrent InitWithContext calls use singleflight +func testConcurrentInit(ctx context.Context, apiKey string, logger *slog.Logger, cfg *conf.SplitSdkConfig) { + // Create a provider but don't initialize + concurrentProvider, err := split.New(apiKey, split.WithLogger(logger), split.WithSplitConfig(cfg)) + if err != nil { + results.Fail("ConcurrentInit(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + defer concurrentProvider.Shutdown() + + // Launch 10 concurrent InitWithContext calls + var wg sync.WaitGroup + errors := make(chan error, 10) + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + for i := 0; i < 10; i++ { + wg.Add(1) + go func() { + defer wg.Done() + initCtx, cancel := context.WithTimeout(ctx, 15*time.Second) + defer cancel() + errors <- concurrentProvider.InitWithContext(initCtx, evalCtx) + }() + } + + wg.Wait() + close(errors) + + // All should succeed (singleflight ensures only one actual init) + successCount := 0 + for err := range errors { + if err == nil { + successCount++ + } + } + + if successCount == 10 { + results.Pass("ConcurrentInit(singleflight)") + } else { + results.Fail("ConcurrentInit(singleflight)", fmt.Sprintf("only %d/10 succeeded", successCount)) + } +} + +// testProviderNotReadyError tests PROVIDER_NOT_READY error code via OpenFeature SDK +func testProviderNotReadyError() { + // Use invalid API key so the provider never becomes ready + uninitProvider, err := split.New("invalid-key-for-not-ready-test") + if err != nil { + results.Fail("ProviderNotReady(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + defer uninitProvider.Shutdown() + + // Use a named provider to avoid interfering with the default provider + ctx := context.Background() + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + // Set as named provider (non-blocking) and immediately try to evaluate + openfeature.SetNamedProvider("not-ready-test", uninitProvider) + client := openfeature.NewClient("not-ready-test") + + details, err := client.BooleanValueDetails(ctx, "some-flag", false, evalCtx) + + if err == nil { + results.Fail("ProviderNotReady(error)", "expected error, got nil") + return + } + + // Check error code - OpenFeature should return PROVIDER_NOT_READY + if details.ErrorCode != openfeature.ProviderNotReadyCode { + results.Fail("ProviderNotReady(error_code)", + fmt.Sprintf("expected PROVIDER_NOT_READY, got %v", details.ErrorCode)) + } else { + results.Pass("ProviderNotReady(error_code)") + } + + // Should return default value + if details.Value != false { + results.Fail("ProviderNotReady(default)", fmt.Sprintf("expected default false, got %v", details.Value)) + } else { + results.Pass("ProviderNotReady(default_value)") + } +} + +// testTrivialGetters tests Metadata() and Hooks() methods +func testTrivialGetters(provider *split.Provider) { + // Test Metadata() + metadata := provider.Metadata() + if metadata.Name != "Split" { + results.Fail("Metadata(name)", fmt.Sprintf("expected Split, got %s", metadata.Name)) + } else { + results.Pass("Metadata(name)") + } + + // Test Hooks() - should return nil + hooks := provider.Hooks() + if hooks != nil { + results.Fail("Hooks()", fmt.Sprintf("expected nil, got %v", hooks)) + } else { + results.Pass("Hooks()") + } +} + +// testInitWithContextTimeout tests InitWithContext with timeout expiration +func testInitWithContextTimeout() { + // Create provider with invalid API key that will never become ready + timeoutProvider, err := split.New("invalid-key-that-will-timeout") + if err != nil { + results.Fail("InitTimeout(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + defer timeoutProvider.Shutdown() + + // Use very short timeout that will expire + initCtx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) + defer cancel() + + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + err = timeoutProvider.InitWithContext(initCtx, evalCtx) + + if err == nil { + results.Fail("InitTimeout(error)", "expected timeout error, got nil") + } else if strings.Contains(err.Error(), "context deadline exceeded") || + strings.Contains(err.Error(), "initialization cancelled") { + results.Pass("InitTimeout(context_cancelled)") + } else { + results.Fail("InitTimeout(error_message)", fmt.Sprintf("unexpected error: %v", err)) + } +} + +// testShutdownWithContextTimeout tests ShutdownWithContext with timeout +func testShutdownWithContextTimeout(apiKey string, logger *slog.Logger, cfg *conf.SplitSdkConfig) { + isLocalhostMode := apiKey == "localhost" + + shutdownProvider, err := split.New(apiKey, split.WithLogger(logger), split.WithSplitConfig(cfg)) + if err != nil { + results.Fail("ShutdownTimeout(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + + initCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + if err := shutdownProvider.InitWithContext(initCtx, evalCtx); err != nil { + results.Fail("ShutdownTimeout(init)", fmt.Sprintf("init failed: %v", err)) + shutdownProvider.Shutdown() + return + } + + // In localhost mode, use very short timeout to test best-effort behavior + // In cloud mode, use longer timeout due to SSE streaming cleanup + var shutdownTimeout time.Duration + if isLocalhostMode { + shutdownTimeout = 1 * time.Millisecond + } else { + shutdownTimeout = 100 * time.Millisecond + } + + shutdownCtx, cancel2 := context.WithTimeout(context.Background(), shutdownTimeout) + defer cancel2() + + err = shutdownProvider.ShutdownWithContext(shutdownCtx) + + // In localhost mode, shutdown should succeed quickly (best-effort) + // In cloud mode with SSE streaming, context timeout is expected + if err != nil { + if strings.Contains(err.Error(), "context deadline exceeded") { + if isLocalhostMode { + // Localhost mode should succeed quickly + results.Fail("ShutdownTimeout(error)", "localhost mode should shutdown quickly") + } else { + // Cloud mode timeout is expected due to SSE streaming + results.Pass("ShutdownTimeout(context_timeout_cloud)") + } + } else { + results.Fail("ShutdownTimeout(error)", fmt.Sprintf("unexpected error: %v", err)) + } + } else { + results.Pass("ShutdownTimeout(best_effort)") + } + + // Provider should be shut down even if timeout expired + if shutdownProvider.Status() != openfeature.NotReadyState { + results.Fail("ShutdownTimeout(status)", "provider should be NotReady after shutdown") + } else { + results.Pass("ShutdownTimeout(status)") + } +} + +// testShutdownDuringInit tests shutdown called during initialization +func testShutdownDuringInit(apiKey string, logger *slog.Logger, cfg *conf.SplitSdkConfig) { + // Create provider with slow initialization + slowProvider, err := split.New(apiKey, split.WithLogger(logger), split.WithSplitConfig(cfg)) + if err != nil { + results.Fail("ShutdownDuringInit(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + + // Start init in background + initDone := make(chan error, 1) + go func() { + initCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + initDone <- slowProvider.InitWithContext(initCtx, evalCtx) + }() + + // Give init a moment to start + time.Sleep(100 * time.Millisecond) + + // Shutdown while init is running + shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + + shutdownErr := slowProvider.ShutdownWithContext(shutdownCtx) + if shutdownErr != nil { + results.Fail("ShutdownDuringInit(shutdown)", fmt.Sprintf("shutdown failed: %v", shutdownErr)) + } else { + results.Pass("ShutdownDuringInit(shutdown)") + } + + initErr := <-initDone + if initErr != nil { + // Init should fail because shutdown happened + results.Pass("ShutdownDuringInit(init_fails)") + } else { + // Or init might succeed before shutdown - both acceptable + results.Pass("ShutdownDuringInit(init_race)") + } + + // Provider should be shut down + if slowProvider.Status() != openfeature.NotReadyState { + results.Fail("ShutdownDuringInit(final_status)", "expected NotReady after shutdown") + } else { + results.Pass("ShutdownDuringInit(final_status)") + } +} + +// testProviderWithNilConfig tests provider creation with nil config +func testProviderWithNilConfig(apiKey string, logger *slog.Logger) { + // For localhost mode, we still need to configure the split file + // This test validates that WithSplitConfig is optional (uses defaults) + // but we configure the split file if in localhost mode + var opts []split.Option + opts = append(opts, split.WithLogger(logger)) + + if apiKey == "localhost" { + cfg := split.TestConfig() + cfg.SplitFile = "./split.yaml" + opts = append(opts, split.WithSplitConfig(cfg)) + } + + nilConfigProvider, err := split.New(apiKey, opts...) + if err != nil { + results.Fail("NilConfig(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + defer nilConfigProvider.Shutdown() + + results.Pass("NilConfig(uses_defaults)") + + // Initialize and verify it works + initCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + if err := nilConfigProvider.InitWithContext(initCtx, evalCtx); err != nil { + results.Fail("NilConfig(init)", fmt.Sprintf("init failed: %v", err)) + } else { + results.Pass("NilConfig(init)") + } +} + +// testBlockUntilReadyZero tests BlockUntilReady=0 uses default timeout +func testBlockUntilReadyZero(apiKey string, logger *slog.Logger) { + // Create optimized test config with BlockUntilReady=0 to test default behavior + cfg := split.TestConfig() + cfg.BlockUntilReady = 0 // Should use default 10s timeout + + // Configure split file for localhost mode + if apiKey == "localhost" { + cfg.SplitFile = "./split.yaml" + } + + zeroProvider, err := split.New(apiKey, split.WithLogger(logger), split.WithSplitConfig(cfg)) + if err != nil { + results.Fail("BlockUntilReadyZero(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + defer zeroProvider.Shutdown() + + results.Pass("BlockUntilReadyZero(create)") + + // Should use default 10s timeout + initCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + if err := zeroProvider.InitWithContext(initCtx, evalCtx); err != nil { + results.Fail("BlockUntilReadyZero(init)", fmt.Sprintf("init failed: %v", err)) + } else { + results.Pass("BlockUntilReadyZero(init_with_default)") + } +} + +// testStatusAtomicity tests Status() method atomicity during lifecycle +func testStatusAtomicity(apiKey string, logger *slog.Logger, cfg *conf.SplitSdkConfig) { + // Create provider + statusProvider, err := split.New(apiKey, split.WithLogger(logger), split.WithSplitConfig(cfg)) + if err != nil { + results.Fail("StatusAtomicity(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + defer statusProvider.Shutdown() + + // Status should be NotReady before init + if statusProvider.Status() != openfeature.NotReadyState { + results.Fail("StatusAtomicity(before_init)", "expected NotReady before init") + } else { + results.Pass("StatusAtomicity(before_init)") + } + + // Initialize + initCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + if err := statusProvider.InitWithContext(initCtx, evalCtx); err != nil { + results.Fail("StatusAtomicity(init)", fmt.Sprintf("init failed: %v", err)) + return + } + + // Status should be Ready after init + if statusProvider.Status() != openfeature.ReadyState { + results.Fail("StatusAtomicity(after_init)", "expected Ready after init") + } else { + results.Pass("StatusAtomicity(after_init)") + } + + // Call Status() concurrently during shutdown + var wg sync.WaitGroup + statusResults := make([]openfeature.State, 100) + + for i := 0; i < 100; i++ { + wg.Add(1) + go func(idx int) { + defer wg.Done() + statusResults[idx] = statusProvider.Status() + }(i) + } + + // Shutdown while Status() is being called + shutdownCtx, cancel2 := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel2() + statusProvider.ShutdownWithContext(shutdownCtx) + + wg.Wait() + + // All status calls should return either Ready or NotReady (atomic, no invalid states) + allValid := true + for _, state := range statusResults { + if state != openfeature.ReadyState && state != openfeature.NotReadyState { + allValid = false + break + } + } + + if !allValid { + results.Fail("StatusAtomicity(during_shutdown)", "invalid state detected") + } else { + results.Pass("StatusAtomicity(during_shutdown)") + } + + // Final status should be NotReady + if statusProvider.Status() != openfeature.NotReadyState { + results.Fail("StatusAtomicity(after_shutdown)", "expected NotReady after shutdown") + } else { + results.Pass("StatusAtomicity(after_shutdown)") + } +} + +// testDoubleShutdown tests shutdown idempotency +func testDoubleShutdown(apiKey string, logger *slog.Logger, cfg *conf.SplitSdkConfig) { + + doubleProvider, err := split.New(apiKey, split.WithLogger(logger), split.WithSplitConfig(cfg)) + if err != nil { + results.Fail("DoubleShutdown(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + + initCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + if err := doubleProvider.InitWithContext(initCtx, evalCtx); err != nil { + results.Fail("DoubleShutdown(init)", fmt.Sprintf("init failed: %v", err)) + doubleProvider.Shutdown() + return + } + + // First shutdown - in cloud mode with SSE streaming, the Split SDK has a known + // hang bug, so we accept context deadline exceeded as a valid outcome + shutdownCtx1, cancel1 := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel1() + err1 := doubleProvider.ShutdownWithContext(shutdownCtx1) + if err1 != nil { + if strings.Contains(err1.Error(), "context deadline exceeded") { + results.Pass("DoubleShutdown(first_timeout_sdk_bug)") + } else { + results.Fail("DoubleShutdown(first)", fmt.Sprintf("first shutdown failed: %v", err1)) + } + return + } + results.Pass("DoubleShutdown(first)") + + // Second shutdown - should be idempotent + shutdownCtx2, cancel2 := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel2() + err2 := doubleProvider.ShutdownWithContext(shutdownCtx2) + if err2 != nil { + results.Fail("DoubleShutdown(second)", fmt.Sprintf("second shutdown failed: %v", err2)) + } else { + results.Pass("DoubleShutdown(idempotent)") + } + + // Status should still be NotReady + if doubleProvider.Status() != openfeature.NotReadyState { + results.Fail("DoubleShutdown(status)", "expected NotReady after double shutdown") + } else { + results.Pass("DoubleShutdown(status)") + } +} diff --git a/test/integration/main.go b/test/integration/main.go new file mode 100644 index 0000000..a7c20df --- /dev/null +++ b/test/integration/main.go @@ -0,0 +1,428 @@ +// Package main is a comprehensive integration test suite for the Split OpenFeature Provider. +// +// This test suite validates ALL provider functionality and serves as both +// integration testing and a reference implementation. It demonstrates: +// +// - Custom Split SDK configuration +// - Structured logging with slog +// - Event handling (PROVIDER_READY, PROVIDER_ERROR, PROVIDER_CONFIGURATION_CHANGED) +// - Graceful shutdown with context cancellation +// - All evaluation types (boolean, string, int, float, object) +// - Evaluation details (variant, reason) +// - Targeting with attributes +// - Context cancellation and timeout handling +// - Flag metadata (configurations attached to flags) +// - Flag set evaluation (cloud mode only) +// - Direct Split SDK access (Track, Treatments) +// - Concurrent evaluations (100 goroutines x 10 evaluations) +// - Comprehensive error handling +// +// This test suite supports both localhost mode and real Split API keys: +// +// Run with localhost mode: go run . +// Run with Split API key: SPLIT_API_KEY=your-key-here go run . +// +// Exit codes: +// - 0: All tests passed +// - 1: One or more tests failed +// - 2: Timeout or fatal error +package main + +import ( + "context" + "fmt" + "log/slog" + "os" + "os/signal" + "strings" + "sync" + "sync/atomic" + "syscall" + "time" + + "github.com/lmittmann/tint" + "github.com/open-feature/go-sdk/openfeature" + "github.com/open-feature/go-sdk/openfeature/hooks" + "github.com/splitio/go-client/v6/splitio/conf" + + "github.com/splitio/split-openfeature-provider-go/v2" +) + +func main() { + fmt.Println(strings.Repeat("=", 60)) + fmt.Println(" Split OpenFeature Provider - Integration Test Suite") + fmt.Println(" Comprehensive Validation & Reference Implementation") + fmt.Println(strings.Repeat("=", 60)) + fmt.Println() + + // ============================================================ + // SETUP: CONTEXT WITH TIMEOUT AND SIGNAL HANDLING + // ============================================================ + + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute) + defer cancel() + + var ( + cleanupSuccess = true + exitCode = 0 + ) + + // ============================================================ + // 1. LOGGING CONFIGURATION (with colored output via tint) + // ============================================================ + + logLevel := slog.LevelInfo + if level := os.Getenv("LOG_LEVEL"); level != "" { + switch level { + case "debug", "DEBUG", "trace", "TRACE": + logLevel = slog.LevelDebug + case "info", "INFO": + logLevel = slog.LevelInfo + case "warn", "WARN", "warning", "WARNING": + logLevel = slog.LevelWarn + case "error", "ERROR": + logLevel = slog.LevelError + default: + logLevel = slog.LevelInfo + } + } + + baseLogger := slog.New(tint.NewHandler(os.Stderr, &tint.Options{ + Level: logLevel, + TimeFormat: time.TimeOnly, + })) + + appLogger := baseLogger.With("source", "app") + ofLogger := baseLogger.With("source", "openfeature-sdk") + + slog.SetDefault(baseLogger) + + section("LOGGING CONFIGURATION") + appLogger.Info("logging configured", "format", "tint (colored)", "level", logLevel.String()) + + // ============================================================ + // 2. OPENFEATURE LOGGING HOOK (must be first to capture all evaluations) + // ============================================================ + section("OPENFEATURE LOGGING HOOK") + openfeature.AddHooks(hooks.NewLoggingHook(false, ofLogger)) + appLogger.Info("logging hook added (captures all flag evaluations)") + + // ============================================================ + // 3. EVENT HANDLERS (API-level handlers run before client handlers) + // ============================================================ + section("EVENT HANDLERS") + + var eventsReceived sync.Map + + handleEvent := func(eventType openfeature.EventType) openfeature.EventCallback { + callback := func(details openfeature.EventDetails) { + val, _ := eventsReceived.LoadOrStore(eventType, new(atomic.Int64)) + counter := val.(*atomic.Int64) + count := counter.Add(1) + + slog.Info("event received", + "type", eventType, + "provider", details.ProviderName, + "message", details.Message, + "count", count) + } + return &callback + } + + openfeature.AddHandler(openfeature.ProviderReady, handleEvent(openfeature.ProviderReady)) + openfeature.AddHandler(openfeature.ProviderError, handleEvent(openfeature.ProviderError)) + openfeature.AddHandler(openfeature.ProviderConfigChange, handleEvent(openfeature.ProviderConfigChange)) + + appLogger.Info("event handlers registered", "handlers", 3) + + // ============================================================ + // 4. SPLIT SDK CONFIGURATION (optimized for fast test execution) + // ============================================================ + section("SPLIT SDK CONFIGURATION") + + apiKey := os.Getenv("SPLIT_API_KEY") + if apiKey == "" { + apiKey = "localhost" + appLogger.Info("no SPLIT_API_KEY provided, using localhost mode") + } else { + appLogger.Info("using Split API key from environment") + } + + // Use optimized test configuration for faster execution + cfg := split.TestConfig() + + if apiKey == "localhost" { + cfg.SplitFile = "./split.yaml" + appLogger.Info("split SDK configured", + "mode", "localhost", + "file", "./split.yaml", + "block_until_ready", cfg.BlockUntilReady) + } else { + appLogger.Info("split SDK configured", + "mode", "cloud", + "block_until_ready", cfg.BlockUntilReady, + "http_timeout", cfg.Advanced.HTTPTimeout) + } + + // ============================================================ + // 5. PROVIDER CREATION + // ============================================================ + section("PROVIDER CREATION") + + provider, err := split.New(apiKey, + split.WithLogger(baseLogger), + split.WithSplitConfig(cfg), + ) + if err != nil { + slog.Error("failed to create provider", "error", err) + os.Exit(2) + } + + appLogger.Info("provider created with unified logging") + + var cleanupOnce sync.Once + cleanup := func() { + cleanupOnce.Do(func() { + defer func() { + if r := recover(); r != nil { + slog.Error("panic during shutdown", "panic", r) + cleanupSuccess = false + } + }() + + fmt.Println() + fmt.Println(strings.Repeat("─", 60)) + slog.Info("initiating graceful shutdown") + + shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if err := openfeature.ShutdownWithContext(shutdownCtx); err != nil { + slog.Error("shutdown error", "error", err) + cleanupSuccess = false + } + + slog.Info("graceful shutdown complete") + }) + } + + defer cleanup() + + shutdownChan := make(chan os.Signal, 1) + done := make(chan struct{}) + signal.Notify(shutdownChan, os.Interrupt, syscall.SIGTERM) + + go func() { + select { + case sig := <-shutdownChan: + slog.Warn("interrupt signal received", "signal", sig) + signal.Stop(shutdownChan) + cancel() + case <-done: + signal.Stop(shutdownChan) + return + } + }() + + defer close(done) + + // ============================================================ + // 6. PROVIDER INITIALIZATION + // ============================================================ + section("PROVIDER INITIALIZATION") + + initCtx, initCancel := context.WithTimeout(context.Background(), 15*time.Second) + defer initCancel() + + if err := openfeature.SetProviderWithContextAndWait(initCtx, provider); err != nil { + slog.Error("failed to initialize provider", "error", err) + cleanup() + os.Exit(2) + } + + appLogger.Info("provider initialized and ready") + + // ============================================================ + // 7. OPENFEATURE CLIENT CREATION + // ============================================================ + section("CLIENT CREATION") + + ofClient := openfeature.NewDefaultClient() + + appLogger.Info("OpenFeature client created") + + // ============================================================ + // RUN ALL TESTS + // ============================================================ + section("RUNNING TESTS") + runTests(ctx, ofClient, provider, &eventsReceived, apiKey, baseLogger, cfg) + + // ============================================================ + // RESULTS SUMMARY + // ============================================================ + results.Summary() + + // Print event statistics + fmt.Println() + fmt.Println("Event Statistics:") + eventsReceived.Range(func(key, value any) bool { + eventType := key.(openfeature.EventType) + counter := value.(*atomic.Int64) + count := counter.Load() + fmt.Printf(" %s: %d events\n", eventType, count) + return true + }) + + close(done) + cleanup() + + if !cleanupSuccess { + exitCode = 2 + } else if results.total.Load() == 0 { + exitCode = 2 + } else if results.failed.Load() > 0 { + exitCode = 1 + } + + os.Exit(exitCode) +} + +// runTests executes all integration tests with the provided context. +func runTests(ctx context.Context, client *openfeature.Client, provider *split.Provider, eventsReceived *sync.Map, apiKey string, baseLogger *slog.Logger, cfg *conf.SplitSdkConfig) { + defer func() { + if r := recover(); r != nil { + slog.Error("panic during test execution", "panic", r) + results.Fail("panic", fmt.Sprintf("test execution panicked: %v", r)) + } + }() + + isLocalhostMode := apiKey == "localhost" + + // ============================================================ + // FLAG EVALUATION TESTS + // ============================================================ + + section("BOOLEAN FLAG EVALUATIONS") + testBooleanEvaluations(ctx, client) + + section("STRING FLAG EVALUATIONS") + testStringEvaluations(ctx, client) + + section("INTEGER FLAG EVALUATIONS") + testIntEvaluations(ctx, client) + + section("FLOAT FLAG EVALUATIONS") + testFloatEvaluations(ctx, client) + + // Object evaluations only work in localhost mode (cloud mode only evaluates flag sets) + if isLocalhostMode { + section("OBJECT FLAG EVALUATIONS") + testObjectEvaluations(ctx, client) + } else { + section("OBJECT FLAG EVALUATIONS (SKIPPED - cloud mode)") + slog.Info("skipping object evaluations - cloud mode only evaluates flag sets") + } + + section("EVALUATION DETAILS") + testEvaluationDetails(ctx, client) + + // Flag metadata tests run in both modes - tests that metadata field is properly populated + // In localhost mode, flags have JSON configs attached + // In cloud mode, flags may or may not have configs (test handles both cases) + section("FLAG METADATA") + testFlagMetadata(ctx, client) + + // Flag set evaluation only works in cloud mode (localhost doesn't support flag sets) + if !isLocalhostMode { + section("FLAG SET EVALUATION") + testFlagSetEvaluation(ctx, client) + } else { + section("FLAG SET EVALUATION (SKIPPED - localhost mode)") + slog.Info("skipping flag set evaluation - localhost mode doesn't support flag sets") + } + + section("TARGETING WITH ATTRIBUTES") + testAttributeTargeting(ctx, client) + + section("CONTEXT CANCELLATION") + testContextCancellation(client) + + section("ERROR HANDLING") + testErrorHandling(ctx, client) + + // ============================================================ + // ADVANCED TESTS (SDK access, concurrency, metrics) + // ============================================================ + + section("EVALUATION MODE OPTIONS") + testObjectEvaluationMode(ctx, provider, isLocalhostMode) + + section("DIRECT SPLIT SDK ACCESS") + testDirectSDKAccess(provider) + + section("CLIENT TRACKING") + testClientTrack(ctx, client) + + section("TRACK OPTIONS") + testTrackWithOptions(ctx, provider) + + section("CONCURRENT EVALUATIONS") + testConcurrentEvaluations(ctx, client) + + section("CLIENT STATE") + testClientState(client) + + section("PROVIDER STATUS & HEALTH") + testProviderHealth(provider) + + section("EVENT TRACKING VALIDATION") + testEventTracking(eventsReceived) + + section("METRICS BEFORE INIT") + testMetricsBeforeInit() + + section("METRICS ALL FIELDS") + testMetricsAllFields(provider) + + // ============================================================ + // LIFECYCLE TESTS (init, shutdown, named providers) + // ============================================================ + + section("INIT AFTER SHUTDOWN") + testInitAfterShutdown(apiKey, baseLogger, cfg) + + section("NAMED PROVIDER SUPPORT") + testNamedProvider(ctx, apiKey, baseLogger, cfg) + + section("CONCURRENT INIT CALLS") + testConcurrentInit(ctx, apiKey, baseLogger, cfg) + + section("PROVIDER_NOT_READY ERROR") + testProviderNotReadyError() + + section("METADATA & HOOKS") + testTrivialGetters(provider) + + section("INIT TIMEOUT") + testInitWithContextTimeout() + + section("SHUTDOWN TIMEOUT") + testShutdownWithContextTimeout(apiKey, baseLogger, cfg) + + section("SHUTDOWN DURING INIT") + testShutdownDuringInit(apiKey, baseLogger, cfg) + + section("METRICS AFTER SHUTDOWN") + testMetricsAfterShutdown(apiKey, baseLogger, cfg) + + section("NIL CONFIG DEFAULTS") + testProviderWithNilConfig(apiKey, baseLogger) + + section("BLOCKUNTILREADY ZERO") + testBlockUntilReadyZero(apiKey, baseLogger) + + section("STATUS ATOMICITY") + testStatusAtomicity(apiKey, baseLogger, cfg) + + section("DOUBLE SHUTDOWN") + testDoubleShutdown(apiKey, baseLogger, cfg) +} diff --git a/test/integration/results.go b/test/integration/results.go new file mode 100644 index 0000000..af51a51 --- /dev/null +++ b/test/integration/results.go @@ -0,0 +1,78 @@ +// results.go provides test result tracking infrastructure. +// It includes atomic counters for pass/fail tracking and proper error aggregation. +package main + +import ( + "fmt" + "log/slog" + "strings" + "sync" + "sync/atomic" + + "github.com/hashicorp/go-multierror" +) + +// TestResults tracks test results with atomic counters and proper error aggregation. +// Uses atomic.Int64 for lock-free counter updates and go-multierror for proper error handling. +type TestResults struct { + passed atomic.Int64 + failed atomic.Int64 + total atomic.Int64 + mu sync.Mutex // Protects result during concurrent Append operations + result *multierror.Error // Accumulated test failures using go-multierror +} + +func (tr *TestResults) Pass(testName string) { + tr.passed.Add(1) + tr.total.Add(1) + slog.Info("PASS", "test", testName) +} + +func (tr *TestResults) Fail(testName string, reason string) { + tr.failed.Add(1) + tr.total.Add(1) + + // Thread-safe error accumulation using go-multierror + tr.mu.Lock() + tr.result = multierror.Append(tr.result, fmt.Errorf("%s: %s", testName, reason)) + tr.mu.Unlock() + + slog.Error("FAIL", "test", testName, "reason", reason) +} + +func (tr *TestResults) Summary() { + tr.mu.Lock() + defer tr.mu.Unlock() + + passed := tr.passed.Load() + failed := tr.failed.Load() + total := tr.total.Load() + + percentage := 0.0 + if total > 0 { + percentage = float64(passed) / float64(total) * 100 + } + + fmt.Println() + fmt.Println(strings.Repeat("=", 60)) + fmt.Printf("Test Results: %d/%d passed (%.1f%%)\n", passed, total, percentage) + if tr.result != nil { + fmt.Println() + fmt.Printf("Failed tests (%d):\n", failed) + fmt.Println(tr.result.Error()) + } else if total > 0 { + fmt.Println("All tests passed!") + } else { + fmt.Println("No tests were run") + } + fmt.Println(strings.Repeat("=", 60)) +} + +var results = new(TestResults) + +// section logs a visually distinct section header for test phases. +func section(name string) { + slog.Info(strings.Repeat("-", 60)) + slog.Info(fmt.Sprintf(">> %s", name)) + slog.Info(strings.Repeat("-", 60)) +} diff --git a/test/integration/sdk.go b/test/integration/sdk.go new file mode 100644 index 0000000..4beb4a0 --- /dev/null +++ b/test/integration/sdk.go @@ -0,0 +1,353 @@ +// sdk.go contains tests for direct SDK access, concurrency, health, and metrics. +// Tests cover Split SDK client access, concurrent evaluations, event tracking, +// provider health status, and metrics before/after initialization. +package main + +import ( + "context" + "fmt" + "log/slog" + "strings" + "sync" + "sync/atomic" + "time" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/conf" + + "github.com/splitio/split-openfeature-provider-go/v2" +) + +// testDirectSDKAccess tests direct access to the Split SDK client +func testDirectSDKAccess(provider *split.Provider) { + + factory := provider.Factory() + splitClient := factory.Client() + + err := splitClient.Track("test-user", "user", "test_event", 1.0, map[string]any{ + "test": "integration_test", + "timestamp": time.Now().Unix(), + }) + + if err != nil { + results.Fail("SDK(Track)", err.Error()) + } else { + results.Pass("SDK(Track)") + } + + treatments := splitClient.Treatments("test-user", []string{ + "feature_boolean_on", + "ui_theme", + "max_retries", + }, nil) + + if len(treatments) != 3 { + results.Fail("SDK(Treatments)", fmt.Sprintf("expected 3 treatments, got %d", len(treatments))) + } else { + results.Pass(fmt.Sprintf("SDK(Treatments) - %d flags evaluated", len(treatments))) + } +} + +// testClientTrack tests the OpenFeature Client.Track() method which uses the provider's Tracker interface +func testClientTrack(ctx context.Context, client *openfeature.Client) { + // Test 1: Basic tracking with default traffic type ("user") + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + details := openfeature.NewTrackingEventDetails(42.0) + + // Track should not panic and should complete (no error return per OpenFeature spec) + client.Track(ctx, "test_event", evalCtx, details) + results.Pass("Client(Track_basic)") + + // Test 2: Tracking with custom traffic type + evalCtxWithTrafficType := openfeature.NewEvaluationContext("test-user", map[string]any{ + "trafficType": "account", + }) + client.Track(ctx, "account_event", evalCtxWithTrafficType, details) + results.Pass("Client(Track_custom_traffic_type)") + + // Test 3: Tracking with properties + detailsWithProps := openfeature.NewTrackingEventDetails(99.99). + Add("currency", "USD"). + Add("item_count", 3). + Add("is_premium", true) + client.Track(ctx, "purchase", evalCtx, detailsWithProps) + results.Pass("Client(Track_with_properties)") + + // Test 4: Tracking with empty targeting key should be silently ignored + emptyEvalCtx := openfeature.NewEvaluationContext("", nil) + client.Track(ctx, "ignored_event", emptyEvalCtx, details) + results.Pass("Client(Track_empty_key_ignored)") +} + +// testTrackWithOptions tests Track with context options (MetricValueAbsent). +func testTrackWithOptions(ctx context.Context, provider *split.Provider) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + // Test 1: Track without metric value (count-only event) + noValueCtx := split.WithoutMetricValue(ctx) + details := openfeature.NewTrackingEventDetails(0) + provider.Track(noValueCtx, "page_view", evalCtx, details) + results.Pass("Track(without_metric_value)") + + // Test 2: Track with metric value (standard) + detailsWithValue := openfeature.NewTrackingEventDetails(99.99) + provider.Track(ctx, "purchase", evalCtx, detailsWithValue) + results.Pass("Track(with_metric_value)") + + // Test 3: Verify context option is correctly set + trackOpts := split.GetTrackOptions(noValueCtx) + if !trackOpts.MetricValueAbsent { + results.Fail("Track(context_option)", "MetricValueAbsent should be true") + } else { + results.Pass("Track(context_option)") + } + + // Test 4: Track with both WithoutMetricValue and non-zero value in details + // MetricValueAbsent should take precedence (nil sent to Split, not 42.0) + precedenceCtx := split.WithoutMetricValue(ctx) + detailsWithNonZero := openfeature.NewTrackingEventDetails(42.0) + provider.Track(precedenceCtx, "count_event", evalCtx, detailsWithNonZero) + results.Pass("Track(absent_takes_precedence)") +} + +// testConcurrentEvaluations tests concurrent flag evaluations +func testConcurrentEvaluations(ctx context.Context, client *openfeature.Client) { + const numGoroutines = 100 + const evaluationsPerGoroutine = 10 + + var wg sync.WaitGroup + errors := make(chan error, numGoroutines*evaluationsPerGoroutine) + + for i := 0; i < numGoroutines; i++ { + wg.Add(1) + go func(id int) { + defer wg.Done() + + evalCtx := openfeature.NewEvaluationContext(fmt.Sprintf("user-%d", id), nil) + + for j := 0; j < evaluationsPerGoroutine; j++ { + _, err := client.BooleanValue(ctx, "feature_boolean_on", false, evalCtx) + if err != nil { + errors <- fmt.Errorf("goroutine %d iteration %d: %w", id, j, err) + } + } + }(i) + } + + wg.Wait() + close(errors) + + errorCount := 0 + for err := range errors { + slog.Error("concurrent evaluation error", "error", err) + errorCount++ + } + + if errorCount > 0 { + results.Fail("Concurrent(evaluations)", fmt.Sprintf("%d errors in %d evaluations", + errorCount, numGoroutines*evaluationsPerGoroutine)) + } else { + results.Pass(fmt.Sprintf("Concurrent(%d goroutines × %d evals)", + numGoroutines, evaluationsPerGoroutine)) + } +} + +// testClientState tests the Client.State() method which queries the provider's status +func testClientState(client *openfeature.Client) { + // Client.State() should return the provider's status via Provider.Status() + state := client.State() + if state != openfeature.ReadyState { + results.Fail("Client(State)", fmt.Sprintf("expected Ready, got %s", state)) + } else { + results.Pass("Client(State)") + } +} + +// testProviderHealth tests provider status and metrics +func testProviderHealth(provider *split.Provider) { + status := provider.Status() + if status != openfeature.ReadyState { + results.Fail("Health(Status)", fmt.Sprintf("expected Ready, got %s", status)) + } else { + results.Pass("Health(Status)") + } + + metrics := provider.Metrics() + + if metrics.Provider != "Split" { + results.Fail("Health(provider)", fmt.Sprintf("expected Split, got %v", metrics.Provider)) + } else { + results.Pass("Health(provider)") + } + + if metrics.Status != openfeature.ReadyState { + results.Fail("Health(status)", fmt.Sprintf("expected Ready, got %v", metrics.Status)) + } else { + results.Pass("Health(status)") + } + + if !metrics.Initialized { + results.Fail("Health(initialized)", "provider should be initialized") + } else { + results.Pass("Health(initialized)") + } +} + +// testEventTracking tests that events are properly tracked +func testEventTracking(eventsReceived *sync.Map) { + // Verify that PROVIDER_READY event was received + if val, ok := eventsReceived.Load(openfeature.ProviderReady); ok { + counter := val.(*atomic.Int64) + count := counter.Load() + if count > 0 { + results.Pass(fmt.Sprintf("Events(PROVIDER_READY) - %d events", count)) + } else { + results.Fail("Events(PROVIDER_READY)", "no events received") + } + } else { + results.Fail("Events(PROVIDER_READY)", "event type not found in sync.Map") + } + + var totalEvents int64 + eventsReceived.Range(func(key, value any) bool { + counter := value.(*atomic.Int64) + totalEvents += counter.Load() + return true + }) + + if totalEvents > 0 { + results.Pass(fmt.Sprintf("Events(Total) - %d total events", totalEvents)) + } else { + results.Fail("Events(Total)", "no events received at all") + } +} + +// testMetricsBeforeInit tests Metrics() before provider initialization +func testMetricsBeforeInit() { + // Use optimized test config with SplitFile to avoid SDK errors looking for ~/.splits + cfg := split.TestConfig() + cfg.SplitFile = "./split.yaml" + + uninitProvider, err := split.New("localhost", split.WithSplitConfig(cfg)) + if err != nil { + results.Fail("MetricsBeforeInit(create)", fmt.Sprintf("failed to create provider: %v", err)) + return + } + defer uninitProvider.Shutdown() + + metrics := uninitProvider.Metrics() + + if metrics.Initialized { + results.Fail("MetricsBeforeInit(initialized)", "expected initialized=false") + } else { + results.Pass("MetricsBeforeInit(initialized)") + } + + if metrics.Status != openfeature.NotReadyState { + results.Fail("MetricsBeforeInit(status)", fmt.Sprintf("expected NotReady, got %s", metrics.Status)) + } else { + results.Pass("MetricsBeforeInit(status)") + } + + if metrics.Ready { + results.Fail("MetricsBeforeInit(ready)", "expected ready=false") + } else { + results.Pass("MetricsBeforeInit(ready)") + } + + if metrics.SplitsCount != -1 { + results.Fail("MetricsBeforeInit(splits_count)", fmt.Sprintf("expected -1 when not ready, got %d", metrics.SplitsCount)) + } else { + results.Pass("MetricsBeforeInit(splits_count)") + } +} + +// testMetricsAllFields tests all Metrics() fields after initialization +func testMetricsAllFields(provider *split.Provider) { + metrics := provider.Metrics() + + if metrics.Provider != "Split" { + results.Fail("MetricsAllFields(provider)", fmt.Sprintf("expected Split, got %s", metrics.Provider)) + } else { + results.Pass("MetricsAllFields(provider)") + } + + if metrics.Status != openfeature.ReadyState { + results.Fail("MetricsAllFields(status)", fmt.Sprintf("expected Ready, got %v", metrics.Status)) + } else { + results.Pass("MetricsAllFields(status)") + } + + if !metrics.Initialized { + results.Fail("MetricsAllFields(initialized)", "expected true") + } else { + results.Pass("MetricsAllFields(initialized)") + } + + if !metrics.Ready { + results.Fail("MetricsAllFields(ready)", "expected true") + } else { + results.Pass("MetricsAllFields(ready)") + } + + if metrics.SplitsCount < 0 { + results.Fail("MetricsAllFields(splits_count)", fmt.Sprintf("invalid count: %d", metrics.SplitsCount)) + } else { + results.Pass(fmt.Sprintf("MetricsAllFields(splits_count=%d)", metrics.SplitsCount)) + } +} + +// testMetricsAfterShutdown tests Metrics() after provider shutdown +func testMetricsAfterShutdown(apiKey string, logger *slog.Logger, cfg *conf.SplitSdkConfig) { + + metricsProvider, err := split.New(apiKey, split.WithLogger(logger), split.WithSplitConfig(cfg)) + if err != nil { + results.Fail("MetricsAfterShutdown(create)", fmt.Sprintf("failed to create: %v", err)) + return + } + + initCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + + if err := metricsProvider.InitWithContext(initCtx, evalCtx); err != nil { + results.Fail("MetricsAfterShutdown(init)", fmt.Sprintf("init failed: %v", err)) + metricsProvider.Shutdown() + return + } + + // Shutdown the provider + // In cloud mode with SSE streaming, the Split SDK has a known hang bug + shutdownCtx, cancel2 := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel2() + if err := metricsProvider.ShutdownWithContext(shutdownCtx); err != nil { + // In cloud mode, shutdown timeout is acceptable due to SSE streaming bug + if apiKey != "localhost" && strings.Contains(err.Error(), "context deadline exceeded") { + // Continue with test - we can still check metrics after timeout + } else { + results.Fail("MetricsAfterShutdown(shutdown)", fmt.Sprintf("shutdown failed: %v", err)) + return + } + } + + // Get metrics after shutdown + metrics := metricsProvider.Metrics() + + if metrics.Status != openfeature.NotReadyState { + results.Fail("MetricsAfterShutdown(status)", fmt.Sprintf("expected NotReady, got %v", metrics.Status)) + } else { + results.Pass("MetricsAfterShutdown(status)") + } + + if metrics.Initialized { + results.Fail("MetricsAfterShutdown(initialized)", "expected false after shutdown") + } else { + results.Pass("MetricsAfterShutdown(initialized)") + } + + if metrics.Ready { + results.Fail("MetricsAfterShutdown(ready)", "expected false after shutdown") + } else { + results.Pass("MetricsAfterShutdown(ready)") + } +} diff --git a/test/integration/split.yaml b/test/integration/split.yaml new file mode 100644 index 0000000..54fafbc --- /dev/null +++ b/test/integration/split.yaml @@ -0,0 +1,107 @@ +# Split Localhost Mode - Integration Test Flags +# +# Format: +# - flag_name: +# treatment: "value" # Required: Treatment (must be a string) +# keys: "key1,key2" # Optional: Comma-separated targeting keys +# config: '{"key": "value"}' # Optional: Dynamic Configuration (JSON) +# +# Documentation: https://developer.harness.io/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/go-sdk#yaml + +# Boolean Flags - Simple on/off features +- feature_boolean_on: + treatment: "on" + config: '{"enabled_at": "2024-01-01T00:00:00Z"}' + +- feature_boolean_off: + treatment: "off" + +# String Flags - Multi-variant features +- ui_theme: + treatment: "dark" + config: '{"primary_color": "#1a1a1a", "accent_color": "#4a9eff"}' + +- api_version: + treatment: "v2" + config: '{"endpoint": "https://api.example.com/v2", "timeout_ms": 5000}' + +# Integer Flags - Numeric configuration +- max_retries: + treatment: "5" + config: '{"backoff_ms": 1000, "exponential": true}' + +- page_size: + treatment: "50" + +- timeout_seconds: + treatment: "30" + +# Float Flags - Percentage and decimal values +- discount_rate: + treatment: "0.15" + config: '{"min_order": 50, "max_discount": 100}' + +- cache_hit_ratio: + treatment: "0.85" + +- sampling_rate: + treatment: "0.01" + +# Object Flags - Complex JSON configuration via Dynamic Configuration +- feature_config: + treatment: "enabled" + config: '{"enabled": true, "rollout_percentage": 100, "metadata": {"owner": "platform-team", "launched": "2024-01-15"}}' + +- premium_features: + treatment: "on" + config: '{"analytics": true, "ai_assistant": true, "priority_support": true, "custom_domains": false}' + +- ab_test_config: + treatment: "treatment_a" + config: '{"variant": "treatment_a", "cohort": "experimental", "tracking_id": "exp_001"}' + +# Targeting with Keys - User-specific overrides +- beta_features: + treatment: "on" + keys: "user-vip,user-beta-tester" + config: '{"features": ["new_dashboard", "advanced_analytics"]}' + +- regional_feature: + treatment: "enabled" + keys: "user-us,user-uk" + +# Control Treatment - Default/fallback behavior +- experimental_algorithm: + treatment: "control" + config: '{"reason": "not_in_experiment"}' + +# System Flags - Operational controls +- maintenance_mode: + treatment: "off" + +- debug_logging: + treatment: "off" + +- rate_limit_enabled: + treatment: "on" + config: '{"requests_per_minute": 1000, "burst": 1500}' + +# Multi-variant Flags - A/B/C testing +- homepage_variant: + treatment: "variant_b" + config: '{"layout": "grid", "hero_image": "v2.jpg", "cta_text": "Get Started"}' + +- pricing_page: + treatment: "pricing_v3" + config: '{"annual_discount": 0.20, "show_enterprise": true}' + +# Migration Flags - Gradual rollout +- new_checkout_flow: + treatment: "on" + keys: "user-vip,user-beta-tester,user-123" + config: '{"version": "2.0", "analytics_tracking": true}' + +# Onboarding Flow - Complex workflow +- onboarding_version: + treatment: "v2" + config: '{"steps": ["welcome", "profile", "preferences", "tutorial", "done"], "skip_allowed": true, "progress_tracking": true}' diff --git a/testdata/split.yaml b/testdata/split.yaml new file mode 100644 index 0000000..4383491 --- /dev/null +++ b/testdata/split.yaml @@ -0,0 +1,37 @@ +# Split Localhost Mode - Unit Test Data +# +# Format: +# - flag_name: +# treatment: "value" # Required: Treatment (must be a string) +# keys: "key1,key2" # Optional: Comma-separated targeting keys +# config: '{"key": "value"}' # Optional: Dynamic Configuration (JSON) +# +# Documentation: https://developer.harness.io/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/go-sdk#yaml + +- my_feature: + treatment: "on" + keys: "key" + config: '{"desc": "this applies only to ON treatment"}' + +- my_feature: + treatment: "off" + +- some_other_feature: + treatment: "off" + +- int_feature: + treatment: "32" + +- obj_feature: + treatment: "on" + config: '{"key": "value"}' + +- float_feature: + treatment: "32.5" + +- unparseable_feature: + treatment: "not-a-valid-type" + +- malformed_json_feature: + treatment: "on" + config: '{invalid json: missing quotes}' \ No newline at end of file diff --git a/track_test.go b/track_test.go new file mode 100644 index 0000000..559b956 --- /dev/null +++ b/track_test.go @@ -0,0 +1,126 @@ +package split + +import ( + "context" + "testing" + + "github.com/open-feature/go-sdk/openfeature" + "github.com/splitio/go-client/v6/splitio/conf" + "github.com/splitio/go-toolkit/v5/logging" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestTrack tests the Track method (Tracker interface). +func TestTrack(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + err = provider.InitWithContext(context.Background(), openfeature.NewEvaluationContext("", nil)) + require.NoError(t, err, "Init should succeed") + + t.Run("basic tracking", func(t *testing.T) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + details := openfeature.NewTrackingEventDetails(42.0) + + // Should not panic - Track returns void + provider.Track(context.Background(), "test_event", evalCtx, details) + }) + + t.Run("tracking with custom traffic type", func(t *testing.T) { + evalCtx := openfeature.NewEvaluationContext("test-user", map[string]any{ + "trafficType": "account", + }) + details := openfeature.NewTrackingEventDetails(99.99) + + // Should not panic + provider.Track(context.Background(), "account_event", evalCtx, details) + }) + + t.Run("tracking with properties", func(t *testing.T) { + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + details := openfeature.NewTrackingEventDetails(149.99). + Add("currency", "USD"). + Add("item_count", 3). + Add("is_premium", true) + + // Should not panic + provider.Track(context.Background(), "purchase", evalCtx, details) + }) + + t.Run("tracking with empty targeting key is ignored", func(t *testing.T) { + evalCtx := openfeature.NewEvaluationContext("", nil) + details := openfeature.NewTrackingEventDetails(1.0) + + // Should not panic - silently ignored + provider.Track(context.Background(), "ignored_event", evalCtx, details) + }) + + t.Run("tracking with canceled context is ignored", func(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + cancel() // Cancel immediately + + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + details := openfeature.NewTrackingEventDetails(1.0) + + // Should not panic - silently ignored due to canceled context + provider.Track(ctx, "canceled_event", evalCtx, details) + }) +} + +// TestTrackProviderNotReady tests that Track is ignored when provider is not ready. +func TestTrackProviderNotReady(t *testing.T) { + cfg := conf.Default() + cfg.SplitFile = testSplitFile + cfg.LoggerConfig.LogLevel = logging.LevelNone + cfg.BlockUntilReady = 10 + + provider, err := New("localhost", WithSplitConfig(cfg)) + require.NoError(t, err, "Failed to create provider") + defer func() { _ = provider.ShutdownWithContext(context.Background()) }() + + // Don't initialize - provider is NotReady + assert.Equal(t, openfeature.NotReadyState, provider.Status(), "Provider should be NotReady") + + evalCtx := openfeature.NewEvaluationContext("test-user", nil) + details := openfeature.NewTrackingEventDetails(1.0) + + // Should not panic - silently ignored because provider not ready + provider.Track(context.Background(), "ignored_event", evalCtx, details) +} + +// ============================================================================= +// Track Options Tests (Localhost Mode) +// ============================================================================= + +func TestTrack_WithoutMetricValue_Localhost(t *testing.T) { + provider := setupLocalhostProvider(t) + + ctx := WithoutMetricValue(context.Background()) + evalCtx := openfeature.NewEvaluationContext("key", nil) + details := openfeature.NewTrackingEventDetails(0) + + // In localhost mode, Track runs the full code path but the SDK discards the event + // (no server to send to). Should not panic. + trackOpts := GetTrackOptions(ctx) + assert.True(t, trackOpts.MetricValueAbsent) + + // Track call should not panic + provider.Track(ctx, "page_view", evalCtx, details) +} + +func TestTrack_WithMetricValue_Localhost(t *testing.T) { + provider := setupLocalhostProvider(t) + + evalCtx := openfeature.NewEvaluationContext("key", nil) + details := openfeature.NewTrackingEventDetails(99.99) + + // Track call should not panic + provider.Track(context.Background(), "purchase", evalCtx, details) +}