{"id":50682734,"url":"https://github.com/switcherapi/switcher-client-go","last_synced_at":"2026-06-08T20:04:11.411Z","repository":{"id":356839614,"uuid":"1233481751","full_name":"switcherapi/switcher-client-go","owner":"switcherapi","description":" [Go] Switcher Client - Go SDK to work with Switcher API - Cloud-based Feature Flag","archived":false,"fork":false,"pushed_at":"2026-06-03T00:18:56.000Z","size":97,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-03T02:07:26.964Z","etag":null,"topics":["feature-flags","go-sdk","switcherapi"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/switcherapi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"petruki","github":["petruki"]}},"created_at":"2026-05-09T02:27:25.000Z","updated_at":"2026-06-03T00:18:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/switcherapi/switcher-client-go","commit_stats":null,"previous_names":["switcherapi/switcher-client-go"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/switcherapi/switcher-client-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/switcherapi%2Fswitcher-client-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/switcherapi%2Fswitcher-client-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/switcherapi%2Fswitcher-client-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/switcherapi%2Fswitcher-client-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/switcherapi","download_url":"https://codeload.github.com/switcherapi/switcher-client-go/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/switcherapi%2Fswitcher-client-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34078059,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["feature-flags","go-sdk","switcherapi"],"created_at":"2026-06-08T20:04:10.228Z","updated_at":"2026-06-08T20:04:11.398Z","avatar_url":"https://github.com/switcherapi.png","language":"Go","funding_links":["https://ko-fi.com/petruki","https://github.com/sponsors/petruki"],"categories":[],"sub_categories":[],"readme":"***\n\n\u003cdiv align=\"center\"\u003e\n\u003cb\u003eSwitcher Client SDK\u003c/b\u003e\u003cbr\u003e\nA Go SDK for Switcher API\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Master CI](https://github.com/switcherapi/switcher-client-go/actions/workflows/master.yml/badge.svg)](https://github.com/switcherapi/switcher-client-go/actions/workflows/master.yml)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=switcherapi_switcher-client-go\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=switcherapi_switcher-client-go)\n![Known Vulnerabilities](https://snyk.io/test/github/switcherapi/switcher-client-go/badge.svg)\n[![Go Report Card](https://goreportcard.com/badge/github.com/switcherapi/switcher-client-go)](https://goreportcard.com/report/github.com/switcherapi/switcher-client-go)\n![Go](https://img.shields.io/badge/go-1.25%2B-blue.svg)\n![Status](https://img.shields.io/badge/status-under_development-orange.svg)\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n[![Slack: Switcher-HQ](https://img.shields.io/badge/slack-@switcher/hq-blue.svg?logo=slack)](https://switcher-hq.slack.com/)\n\n\u003c/div\u003e\n\n***\n\n![Switcher API: Go Client: Cloud-based Feature Flag API](https://github.com/switcherapi/switcherapi-assets/blob/master/logo/switcherapi_go_client.png)\n\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n\t- [System Requirements](#system-requirements)\n- [Configuration](#configuration)\n\t- [Basic Setup](#basic-setup)\n\t- [Advanced Configuration](#advanced-configuration)\n\t- [Security Features](#security-features)\n- [Usage Examples](#usage-examples)\n\t- [Basic Feature Flag Checking](#basic-feature-flag-checking)\n\t- [Detailed Response Information](#detailed-response-information)\n\t- [Must-variant with default](#must-variant-with-default-response)\n\t- [Strategy-Based Feature Flags](#strategy-based-feature-flags)\n\t- [Error Handling](#error-handling)\n- [Advanced Features](#advanced-features)\n\t- [Throttling](#throttling)\n\t- [Hybrid Mode](#hybrid-mode)\n\t- [Circuit Breaker](#circuit-breaker-silent-mode)\n- [Snapshot Management](#snapshot-management)\n\t- [Loading Snapshots](#loading-snapshots)\n\t- [Version Management](#version-management)\n\t- [Automated Updates](#automated-updates)\n\t- [Snapshot Monitoring](#snapshot-monitoring)\n- [Testing \u0026 Development](#testing--development)\n\t- [Built-in Mocking](#built-in-mocking)\n\t- [Test Helpers](#test-helpers)\n\t- [Configuration Validation](#configuration-validation)\n- [Contributing](#contributing)\n\n---\n\n## About\n\nThe **Switcher Client SDK for Go** provides integration with [Switcher-API](https://github.com/switcherapi/switcher-api), enabling feature flag management in Go applications.\n\n\u003e Features marked as **Under development** are part of the current SDK roadmap and may not be available in the repository yet.\n\n### Key Features\n\n- **Clean \u0026 Maintainable**: Simple package-level access with an instance-based core\n- **Local Mode**: Offline execution using snapshot files from your Switcher-API domain\n- **Silent Mode**: Hybrid configuration with automatic fallback for connectivity issues\n- **Built-in Testing Helpers (Under development)**: Test-oriented mocking support adapted for Go\n- **Zero Latency**: Local snapshot execution for high-performance scenarios\n- **Secure**: Regex protections and configurable remote transport settings\n- **Monitoring**: Execution logging, caching, and error notification hooks\n\n## Quick Start\n\nGet up and running in just a few lines of code:\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/switcherapi/switcher-client-go\"\n)\n\nfunc main() {\n\tclient.BuildContext(client.Context{\n\t\tDomain:      \"My Domain\",\n\t\tURL:         \"https://api.switcherapi.com\",\n\t\tAPIKey:      \"[YOUR_API_KEY]\",\n\t\tComponent:   \"MyApp\",\n\t\tEnvironment: \"default\",\n\t})\n\n\tswitcher := client.GetSwitcher(\"FEATURE_TOGGLE\")\n\tenabled, err := switcher.IsOn()\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tif enabled {\n\t\tfmt.Println(\"Feature is enabled!\")\n\t}\n}\n```\n\n## Installation\n\nInstall the Switcher Client SDK:\n\n```bash\ngo get github.com/switcherapi/switcher-client-go\n```\n\n### System Requirements\n- **Go**: 1.25+ (targeting 1.25.x and 1.26.x)\n- **Operating System**: Cross-platform (Windows, macOS, Linux)\n\n## Configuration\n\n### Basic Setup\n\nInitialize the Switcher Client with your domain configuration:\n\n```go\npackage main\n\nimport (\n\t\"github.com/switcherapi/switcher-client-go\"\n)\n\nfunc main() {\n\tclient.BuildContext(client.Context{\n\t\tDomain:      \"My Domain\",                \t// Your Switcher domain name\n\t\tURL:         \"https://api.switcherapi.com\", // Switcher-API endpoint (optional)\n\t\tAPIKey:      \"[YOUR_API_KEY]\",           \t// Your component's API key (optional)\n\t\tComponent:   \"MyApp\",                    \t// Your application name (optional)\n\t\tEnvironment: \"default\",                  \t// Environment (\"default\" for production)\n\t})\n\n\tswitcher := client.GetSwitcher(\"FEATURE_LOGIN_V2\")\n\t_ = switcher\n}\n```\n\n#### Configuration Parameters\n\n| Parameter | Required | Description | Default |\n|-----------|----------|-------------|---------|\n| `Domain` | ✅ | Your Switcher domain name | - |\n| `URL` |  | Switcher-API endpoint | `https://api.switcherapi.com` |\n| `APIKey` |  | API key for your component | - |\n| `Component` |  | Your application identifier | - |\n| `Environment` |  | Target environment | `default` |\n\n### Advanced Configuration\n\nEnable additional features like local mode, silent mode, and transport options:\n\n```go\npackage main\n\nimport (\n\t\"time\"\n\n\t\"github.com/switcherapi/switcher-client-go\"\n)\n\nfunc main() {\n\tclient.BuildContext(client.Context{\n\t\tDomain:      \"My Domain\",\n\t\tURL:         \"https://api.switcherapi.com\",\n\t\tAPIKey:      \"[YOUR_API_KEY]\",\n\t\tComponent:   \"MyApp\",\n\t\tEnvironment: \"default\",\n\t\tOptions: client.ContextOptions{\n\t\t\tLocal:                      true,\n\t\t\tLogger:                     true,\n\t\t\tFreeze:                     true,\n\t\t\tSnapshotLocation:           \"./snapshot/\",\n\t\t\tSnapshotAutoUpdateInterval: 30 * time.Second,\n\t\t\tSilentMode:                 5 * time.Minute,\n\t\t\tRestrictRelay:              true,\n\t\t\tThrottleMaxWorkers:         2,\n\t\t\tRegexMaxBlacklist:          10,\n\t\t\tRegexMaxTimeLimit:          100 * time.Millisecond,\n\t\t\tRemote: client.RemoteOptions{\n\t\t\t\tCertPath:       \"./certs/ca.pem\",\n\t\t\t\tConnectTimeout: 300 * time.Millisecond,\n\t\t\t\tTimeout:        5 * time.Second,\n\t\t\t},\n\t\t},\n\t})\n\n\tswitcher := client.GetSwitcher(\"FEATURE_LOGIN_V2\")\n\t_ = switcher\n}\n```\n\n#### Advanced Options Reference\n\n| Option | Type | Description | Default |\n|--------|------|-------------|---------|\n| `Local` | `bool` | Use local snapshot files only (zero latency) | `false` |\n| `Logger` | `bool` | Enable logging/caching of feature flag evaluations | `false` |\n| `Freeze` | `bool` | Enable cache-immutability responses for consistent results | `false` |\n| `SnapshotLocation` | `string` | Directory for snapshot files | `\"\"` |\n| `SnapshotAutoUpdateInterval` | `time.Duration` | Auto-update interval for snapshots | `0` |\n| `SilentMode` | `time.Duration` | Silent mode retry time before returning to remote mode | `0` |\n| `RestrictRelay` | `bool` | Enable relay restrictions in local mode | `true` |\n| `ThrottleMaxWorkers` | `int` | Max workers for throttling refresh tasks | runtime-defined |\n| `RegexMaxBlacklist` | `int` | Max cached entries for failed regex | `100` |\n| `RegexMaxTimeLimit` | `time.Duration` | Regex execution time limit | `3s` |\n| `Remote` | `RemoteOptions` | Remote transport settings | `RemoteOptions{}` |\n\n`RemoteOptions` fields:\n\n| Option | Type | Description | Default |\n|--------|------|-------------|---------|\n| `CertPath` | `string` | Path to custom certificate for secure API connections | `\"\"` |\n| `ConnectTimeout` | `time.Duration` | Max time to establish a remote connection before failing fast | `300ms` |\n| `Timeout` | `time.Duration` | Max time for remote request/response and idle connection reuse | `5s` |\n\n**Note:** lower remote connect timeouts help silent mode fall back faster when the upstream is unavailable.\n\n#### Security Features\n\n- **ReDoS Protection (Under development)**: Regex safety features with bounded execution time\n- **Time Limits**: Configurable timeouts for regex and remote operations\n- **Certificate Support**: Custom certificates for secure API connections\n\n## Usage Examples\n\n### Basic Feature Flag Checking\n\nThe simplest way to check if a feature is enabled:\n\n```go\nswitcher := client.GetSwitcher(\"FEATURE_LOGIN_V2\")\n\nenabled, err := switcher.IsOn()\nif err != nil {\n\tpanic(err)\n}\n\nif enabled {\n\tnewLogin()\n} else {\n\tlegacyLogin()\n}\n```\n\n### Detailed Response Information\n\nGet comprehensive information about the feature flag evaluation:\n\n```go\nresponse, err := client.GetSwitcher(\"FEATURE_LOGIN_V2\").IsOnWithDetails()\nif err != nil {\n\tpanic(err)\n}\n\nfmt.Printf(\"Feature enabled: %v\\n\", response.Result)\nfmt.Printf(\"Reason: %s\\n\", response.Reason)\nfmt.Printf(\"Metadata: %#v\\n\", response.Metadata)\n```\n\n### Must-variant with default response:\n\nSimpified response handling with default values when errors occur:\n\n```go\nfeature := client.GetSwitcher(\"FEATURE_LOGIN_V2\")\n\nenabled = feature.IsOnOrDefault(false)\nresponse := feature.IsOnWithDetailsOrDefault(ResultDetail{\n\tResult: false,\n\tReason: \"default\",\n})\n```\n\nUse the async error channel for non-blocking error handling:\n\n```go\nclient.SubscribeNotifyError(func(err error) {\n\tfmt.Printf(\"Switcher Error: %v\\n\", err)\n})\n```\n\n### Strategy-Based Feature Flags\n\n#### Method 1: Prepare and Execute\n\nLoad validation data separately, useful for complex applications:\n\n```go\nprepared := client.GetSwitcher(\"\").\n\tCheckValue(\"USER_123\")\n\nif err := prepared.Prepare(\"USER_FEATURE\"); err != nil {\n\tpanic(err)\n}\n\nenabled, err := prepared.IsOn()\nif err != nil {\n\tpanic(err)\n}\n\nif enabled {\n\tenableUserFeature()\n}\n```\n\n#### Method 2: All-in-One Execution\n\nChain multiple validation strategies for comprehensive feature control:\n\n```go\nisEnabled, err := client.GetSwitcher(\"PREMIUM_FEATURES\").\n\tCheckValue(\"premium_user\").\n\tCheckNetwork(\"192.168.1.0/24\").\n\tDefaultResult(true).\n\tThrottle(time.Second).\n\tIsOn()\n\nif err != nil {\n\tpanic(err)\n}\n\nif isEnabled {\n\tshowPremiumDashboard()\n}\n```\n\n### Error Handling\n\nSubscribe to error notifications for robust error management:\n\n```go\nclient.SubscribeNotifyError(func(err error) {\n\tfmt.Printf(\"Switcher Error: %v\\n\", err)\n})\n```\n\n## Advanced Features\n\n#### Throttling\n\nThrottle implements Stale-While-Revalidate behavior for feature flag evaluations, returning cached results while refreshing in the background. This is ideal for high-traffic scenarios where you want to minimize latency and avoid overwhelming the API with requests.\n\n```go\n_, err := client.GetSwitcher(\"FEATURE01\").Throttle(time.Second).IsOn()\nif err != nil {\n\tpanic(err)\n}\n```\n\nThrottle reuses the latest cached execution for the same switcher key and inputs. It records that cached execution even when `ContextOptions.Logger` is `false`, and when `Freeze` is enabled the cached value stays in place until `client.ClearLogger()` is called.\n\n```go\nswitcher := client.GetSwitcher(\"FEATURE01\").Throttle(time.Second)\n_, _ = switcher.IsOnWithDetails()\n\nlogged := client.GetExecution(switcher)\nfmt.Println(logged.Response.Metadata[\"cached\"])\n```\n\n#### Hybrid Mode\n```go\n_, err := client.GetSwitcher(\"FEATURE01\").Remote().IsOn()\nif err != nil {\n\tpanic(err)\n}\n```\n\n#### Circuit Breaker: Silent Mode\n\nThis feature allows you to specify how long the client SDK should attempt to restore connectivity in case of remote API failures.\n\nWhen the API is unavailable, the SDK will automatically operate in silent mode, evaluating Switchers using a local snapshot. It is important to note that any Switcher Key configured must be able to resolve without external dependencies (e.g., Switcher Relay).\n\nMake sure to configure the scheduled snapshot auto-update to keep the local snapshot up to date with the remote API.\n\nHere is an example - in-memory snapshot with auto-update every 30 seconds:\n\n```go\nclient.BuildContext(client.Context{\n\tDomain:      \"My Domain\",\n\tURL:         \"https://api.switcherapi.com\",\n\tAPIKey:      \"[YOUR_API_KEY]\",\n\tComponent:   \"MyApp\",\n\tOptions: client.ContextOptions{\n\t\tSnapshotAutoUpdateInterval: 30 * time.Second,\n\t\tSilentMode:                 5 * time.Minute,\n\t},\n})\n```\n\n## Snapshot Management\n\n### Loading Snapshots\n\nLoad snapshots from the API or local files:\n\n```go\nversion, err := client.LoadSnapshot(nil)\nif err != nil {\n\tpanic(err)\n}\n\nfmt.Println(version)\n```\n\n```go\nversion, err := client.LoadSnapshot(\u0026client.LoadSnapshotOptions{\n\tFetchRemote: true,\n})\nif err != nil {\n\tpanic(err)\n}\n\nfmt.Println(version)\n```\n\n```go\n_, err := client.LoadSnapshot(\u0026client.LoadSnapshotOptions{\n\tWatchSnapshot: true,\n})\nif err != nil {\n\tpanic(err)\n}\n```\n\n### Version Management\n\nCheck your current snapshot version:\n\n```go\nupdated, err := client.CheckSnapshot()\nif err != nil {\n\tpanic(err)\n}\n\nfmt.Printf(\"Snapshot updated: %v\\n\", updated)\nfmt.Printf(\"Current snapshot version: %d\\n\", client.SnapshotVersion())\n```\n\n### Automated Updates\n\nSchedule automatic snapshot updates for zero-latency local mode:\n\n```go\nclient.ScheduleSnapshotAutoUpdate(time.Minute, func(err error, updated bool) {\n\tif err != nil {\n\t\tfmt.Printf(\"snapshot update error: %v\\n\", err)\n\t\treturn\n\t}\n\n\tif updated {\n\t\tfmt.Printf(\"Snapshot updated to version: %d\\n\", client.SnapshotVersion())\n\t}\n})\n```\n\n### Snapshot Monitoring\n\n```go\nerr := client.WatchSnapshot(client.WatchSnapshotCallback{\n\tSuccess: func() {\n\t\tfmt.Println(\"snapshot loaded successfully\")\n\t},\n\tReject: func(err error) {\n\t\tfmt.Printf(\"error loading snapshot: %v\\n\", err)\n\t},\n})\nif err != nil {\n\tpanic(err)\n}\n```\n\n## Testing \u0026 Development\n\n### Built-in Mocking (Under development)\n\nThe Go SDK provides test-oriented mocking capabilities adapted to Go idioms and safer state ownership.\n\n```go\nsdk := client.NewClient(ctx)\nsdk.Assume(\"FEATURE01\").True()\n\nenabled, err := sdk.GetSwitcher(\"FEATURE01\").IsOn()\nassert.NoError(t, err)\nassert.True(t, enabled)\n```\n\n```go\nsdk.Assume(\"FEATURE01\").True().\n\tWhen(client.StrategyValue, []string{\"guest\", \"admin\"}).\n\tWhen(client.StrategyNetwork, \"10.0.0.3\")\n\nenabled, err := sdk.GetSwitcher(\"FEATURE01\").\n\tCheckValue(\"guest\").\n\tCheckNetwork(\"10.0.0.3\").\n\tIsOn()\nassert.NoError(t, err)\nassert.True(t, enabled)\n```\n\n```go\nsdk.Forget(\"FEATURE01\")\n```\n\n```go\nsdk.Assume(\"FEATURE01\").False().WithMetadata(map[string]any{\n\t\"message\": \"Feature is disabled\",\n})\n\nresponse, err := sdk.GetSwitcher(\"FEATURE01\").IsOnWithDetails()\nassert.NoError(t, err)\nassert.Equal(t, false, response.Result)\nassert.Equal(t, \"Feature is disabled\", response.Metadata[\"message\"])\n```\n\n### Test Helpers (Under development)\n\nThis area is under active development. The helper surface focuses on:\n\n- explicit test helpers instead of decorators\n- automatic cleanup helpers for tests where useful\n- mock isolation by client instance and, when needed, `context.Context`\n\n### Configuration Validation\n\nValidate your feature flag configuration before deployment:\n\n```go\nerr := client.CheckSwitchers([]string{\n\t\"FEATURE_LOGIN\",\n\t\"FEATURE_DASHBOARD\",\n\t\"FEATURE_PAYMENTS\",\n})\nif err != nil {\n\tfmt.Printf(\"Configuration error: %v\\n\", err)\n}\n```\n\nThis validation helps prevent deployment issues by ensuring all required feature flags are properly set up in your Switcher domain.\n\n## Contributing\nWe welcome contributions to the Switcher Client SDK for Go. If you have suggestions, improvements, or bug fixes, please follow these steps:\n\n1. Fork the repository.\n2. Create a new branch for your feature or bug fix.\n3. Make your changes and commit them with clear messages.\n4. Submit a pull request detailing your changes and the problem they solve.\n\nThank you for helping us improve the Switcher Client SDK for Go.\n\n### Requirements\n- Go 1.25 or higher\n- A local Switcher API environment or test fixtures for development\n- Standard Go tooling (`go test`, `gofmt`)\n- `golangci-lint` for repository lint checks (`make lint-install`)\n\n# AI Disclaimer\n\nThis project was ported from [switcherapi/switcher-client-py](https://github.com/switcherapi/switcher-client-py) and adapted for Go using AI-assisted tools. We have thoroughly reviewed and tested all AI-generated contributions to ensure they meet our quality standards and align with our project's goals. We are committed to transparency about our use of AI and will continue to disclose any significant AI contributions in the future. \n\nExternal contributions from the community are **equally valued and will be reviewed with the same standards, regardless of whether they were assisted by AI or not**. We encourage all contributors to disclose their use of AI tools in their contributions to maintain transparency and foster trust within our community.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswitcherapi%2Fswitcher-client-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswitcherapi%2Fswitcher-client-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswitcherapi%2Fswitcher-client-go/lists"}