Superposition

https://github.com/juspay/superposition
Admin
Superposition is a configuration and experimentation management platform that allows software teams...
Tokens:1,225,259
Snippets:6,851
Trust Score:10
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quick start with LocalResolutionProvider

Source: https://github.com/juspay/superposition/blob/main/docs/docs/providers/openfeature/rust.md

This example shows how to set up the LocalResolutionProvider with an HTTP data source, polling refresh strategy, and evaluate feature flags using the OpenFeature API.

```rust
use open_feature::{EvaluationContext, OpenFeature};
use superposition_provider::{
    data_source::http::HttpDataSource,
    local_provider::LocalResolutionProvider,
    PollingStrategy, RefreshStrategy, SuperpositionOptions,
};
use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() {
    env_logger::init();

    // 1. Create an HTTP data source pointing to your Superposition server
    let http_source = HttpDataSource::new(SuperpositionOptions::new(
        "http://localhost:8080".to_string(),
        "your_token_here".to_string(),
        "localorg".to_string(),
        "test".to_string(),
    ));

    // 2. Create the provider with a polling refresh strategy
    let provider = LocalResolutionProvider::new(
        Box::new(http_source),
        None, // no fallback data source
        RefreshStrategy::Polling(PollingStrategy {
            interval: 60,       // seconds between polls
            timeout: Some(30),  // HTTP request timeout in seconds
        }),
    );

    // 3. Register with OpenFeature and create a client
    let mut api = OpenFeature::singleton_mut().await;
    api.set_provider(provider).await;
    let client = api.create_client();

    // Allow time for the provider to initialize
    sleep(Duration::from_secs(2)).await;

    // 4. Evaluate feature flags
    let context = EvaluationContext::default()
        .with_targeting_key("user-42")
        .with_custom_field("city", "Berlin");

    let string_val = client
        .get_string_value("currency", Some(&context), None)
        .await
        .unwrap();
    println!("currency = {}", string_val);

    let int_val = client
        .get_int_value("price", Some(&context), None)
        .await
        .unwrap();
    println!("price = {}", int_val);

    let bool_val = client
        .get_bool_value("dark_mode", Some(&context), None)
        .await
        .unwrap();
    println!("dark_mode = {}", bool_val);
}

```

--------------------------------

### Running the Examples

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Run the examples with the local development server.

```bash
docker run -p 8080:8080 superposition:latest
```

--------------------------------

### Running the Examples

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Run the examples with the local development server.

```bash
python polling_example.py
```

--------------------------------

### Running the Examples

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Run the examples with the local development server.

```bash
python local_example.py
```

--------------------------------

### Running the Examples

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Run the examples with the local development server.

```bash
python fallback_example.py
```

--------------------------------

### Install plugin with vim-plug

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/neovim-extension/README.md

Adds the plugin using vim-plug with the runtime path set. Then add the setup call to init.lua.

```vim
Plug "superposition/superposition", { "rtp": "tooling/lsp/neovim-extension" }
```

```lua
require("supertoml-analyzer").setup()
```

--------------------------------

### Running the Examples

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Run the examples with the local development server.

```bash
python file_watch_example.py
```

--------------------------------

### Running the Examples

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Run the examples with the local development server.

```bash
python http_example.py
```

--------------------------------

### Install plugin with packer.nvim

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/neovim-extension/README.md

Configures the plugin using packer.nvim, setting the runtime path and calling setup with no arguments.

```lua
use {
    "superposition/superposition",
    rtp = "tooling/lsp/neovim-extension",
    config = function()
        require("supertoml-analyzer").setup()
    end,
    ft = { "superTOML" },
}
```

--------------------------------

### Installation

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Install the required dependencies.

```bash
pip install superposition-sdk
```

--------------------------------

### Quick Start: LocalResolutionProvider with polling

Source: https://github.com/juspay/superposition/blob/main/docs/docs/providers/openfeature/python.md

Complete example showing how to create an HTTP data source, configure a LocalResolutionProvider with a polling refresh strategy, initialize it, register with OpenFeature, evaluate flags of different types, and shut down. Uses asyncio.

```python
import asyncio
from openfeature import api
from openfeature.evaluation_context import EvaluationContext
from superposition_provider import (
    LocalResolutionProvider,
    HttpDataSource,
    SuperpositionOptions,
    PollingStrategy,
    RefreshStrategy,
)


async def main():
    # 1. Create an HTTP data source pointing to your Superposition server
    http_source = HttpDataSource(SuperpositionOptions(
        endpoint="http://localhost:8080",
        token="your-api-token",
        org_id="localorg",
        workspace_id="test",
    ))

    # 2. Create the provider with a polling refresh strategy
    provider = LocalResolutionProvider(
        data_source=http_source,
        fallback_source=None,  # no fallback data source
        refresh_strategy=RefreshStrategy.Polling(PollingStrategy(
            interval=60,   # seconds between polls
            timeout=30,    # HTTP request timeout in seconds
        )),
    )

    # 3. Set up evaluation context (dimensions + targeting key)
    ctx = EvaluationContext(
        targeting_key="user-42",
        attributes={"city": "Berlin", "os": "android"},
    )

    # 4. Initialize the provider (async — starts polling, fetches initial config)
    await provider.initialize(context=ctx)

    # 5. Register with OpenFeature
    api.set_provider(provider)
    client = api.get_client()

    # 6. Evaluate feature flags
    string_val = client.get_string_details("currency", "USD", ctx)
    print(f"currency = {string_val.value}")

    int_val = client.get_integer_details("price", 0, ctx)
    print(f"price = {int_val.value}")

    bool_val = client.get_boolean_details("dark_mode", False, ctx)
    print(f"dark_mode = {bool_val.value}")

    float_val = client.get_float_details("discount_rate", 0.0, ctx)
    print(f"discount_rate = {float_val.value}")

    # 7. Cleanup — stops polling, releases resources
    await provider.shutdown()


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Manual installation: install dependencies and compile

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/vscode-extension/README.md

Run this command in the copied vscode-extension directory to install dependencies and compile the extension for manual installation.

```bash
npm install && npm run compile
```

--------------------------------

### Module Functions: Setup, Start, Stop, Restart, Attach, Status, Info, Health

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/neovim-extension/README.md

Core API functions for the SuperTOML Analyzer plugin. Use setup() to configure, start()/stop()/restart() to manage the language server, attach(bufnr) to attach to a buffer (defaults to current), is_running() and status() to check state, info() for plugin info, and check_health() for diagnostics.

```lua
local supertoml = require("supertoml-analyzer")

-- Setup the plugin
supertoml.setup({ /* config */ })

-- Start/stop/restart the language server
supertoml.start()
supertoml.stop()
supertoml.restart()

-- Attach to a buffer
supertoml.attach(bufnr)  -- bufnr is optional, defaults to current buffer

-- Check status
supertoml.is_running()  -- Returns boolean
supertoml.status()      -- Returns "running", "stopped", or "not started"

-- Get plugin info
supertoml.info()        -- Returns table with plugin info

-- Health check
supertoml.check_health()
```

--------------------------------

### Start the development server

Source: https://github.com/juspay/superposition/blob/main/examples/dynamic-payment-fields/README.md

Starts the Vite development server.

```bash
npm run dev
```

--------------------------------

### Setup database and environment variables

Source: https://github.com/juspay/superposition/blob/main/docs/docs/setup.md

Runs the make setup target to initialize the database and set up environment variables.

```bash
make setup
```

--------------------------------

### Install Go package

Source: https://github.com/juspay/superposition/blob/main/clients/go/Readme.md

Installs the Go client package from the repository.

```bash
go get github.com/juspay/superposition/clients/go
```

--------------------------------

### Install make and yq on Linux

Source: https://github.com/juspay/superposition/blob/main/docs/docs/setup.md

Installs build-essential and yq on Linux using apt-get.

```bash
sudo apt-get install build-essential yq
```

--------------------------------

### Clone and run Superposition from repository

Source: https://github.com/juspay/superposition/blob/main/README.md

Clones the Superposition repository, optionally enters the Nix dev shell, starts local dependencies (Postgres/Redis) with podman compose, and runs the setup and server. Note: 'docker compose up -d' only starts dependencies, not the UI/API; use 'make run' to launch the server.

```bash
git clone https://github.com/juspay/superposition.git
cd superposition
# Optional: enter the Nix dev shell if you use Nix
nix develop

# Start local dependencies (Postgres/Redis)
podman compose up -d

# Set up the dev environment and run Superposition
make setup
make run
```

--------------------------------

### Run the example with cargo run

Source: https://github.com/juspay/superposition/blob/main/examples/superposition_toml_example/README.md

Run the example from the repository root. This compiles and runs the superposition_toml_example crate, demonstrating various pricing scenarios.

```bash
cargo run -p superposition_toml_example
```

--------------------------------

### Install dependencies with bun install

Source: https://github.com/juspay/superposition/blob/main/tests/README.md

Run this command in the project root to install all required dependencies using Bun.

```bash
bun install
```

--------------------------------

### TreeSitter Integration: nvim-treesitter Setup

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/neovim-extension/README.md

Setup for nvim-treesitter to ensure the TOML parser is installed, required for the plugin's TreeSitter queries.

```lua
-- Using nvim-treesitter
require("nvim-treesitter.configs").setup({
    ensure_installed = { "toml" },
})
```

--------------------------------

### Run Superposition demo image with Docker

Source: https://github.com/juspay/superposition/blob/main/README.md

Starts the Superposition demo container with a preloaded setup on port 8080. After running, open http://localhost:8080 to explore the admin interface.

```bash
docker run -p 8080:8080 ghcr.io/juspay/superposition-demo:latest
```

--------------------------------

### Run the reference introspection service

Source: https://github.com/juspay/superposition/blob/main/examples/token-introspection/README.md

Install dependencies and start the service with the required INTROSPECTION_AUTH_TOKEN environment variable. The service listens on port 4000 at /introspect.

```bash
npm install
INTROSPECTION_AUTH_TOKEN=my-caller-secret npm start
# listening on :4000/introspect
```

--------------------------------

### Start local development server with yarn start

Source: https://github.com/juspay/superposition/blob/main/docs/README.md

Starts a local development server and opens a browser window. Most changes are reflected live without restarting the server.

```bash
yarn start
```

--------------------------------

### Run the example binary with cargo

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/examples.md

Runs the ready-to-run example binary from the superposition_config_file_examples crate. It parses both example.toml and example.json and demonstrates various resolution scenarios.

```bash
cd examples/superposition_config_file_examples
cargo run
```

--------------------------------

### Clone the Superposition repository and navigate to the example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/applications/k8s-staggered-releaser.md

Commands to clone the repository and change into the k8s-staggered-releaser example directory.

```bash
git clone https://github.com/juspay/superposition.git
cd superposition/examples/k8s-staggered-releaser
```

--------------------------------

### Install @superposition/toml-bindings

Source: https://github.com/juspay/superposition/blob/main/clients/javascript/bindings/README_TOML_TESTS.md

Install the package via npm.

```bash
npm install @superposition/toml-bindings
```

--------------------------------

### Run the example with cargo

Source: https://github.com/juspay/superposition/blob/main/examples/superposition_config_file_examples/README.md

Command to compile and run the example from the repository root. It demonstrates various pricing scenarios using both TOML and JSON formats.

```bash
cargo run -p superposition_config_file_examples
```

--------------------------------

### Install docs dependencies and build HTML with Sphinx

Source: https://github.com/juspay/superposition/blob/main/clients/python/sdk/docs/README.md

Run these commands to install the documentation dependencies and generate HTML documentation locally. The first command uses uv to install the package with the 'docs' extra, and the second builds the documentation with make in the docs directory.

```bash
$ uv pip install ".[docs]"
$ cd docs
$ make html
```

--------------------------------

### LocalResolutionProvider setup and usage

Source: https://github.com/juspay/superposition/blob/main/docs/docs/providers/openfeature/haskell.md

Configures a LocalResolutionProvider with an HTTP data source, polling refresh strategy, and optional fallback. Initializes the provider, resolves all features, gets applicable variants, and cleans up. Requires imports from Data.OpenFeature and Data.OpenFeature.SuperpositionProvider.

```haskell
import Data.OpenFeature (EvaluationContext(..))
import Data.OpenFeature.SuperpositionProvider
    ( HttpDataSource(..), LocalResolutionProvider(..)
    , AllFeatureProvider(..), FeatureExperimentMeta(..)
    , PollingStrategy(..), RefreshStrategy(..), SuperpositionOptions(..)
    )

let httpSource = HttpDataSource $ SuperpositionOptions
        { endpoint    = "http://localhost:8080"
        , token       = "token"
        , orgId       = "localorg"
        , workspaceId = "dev"
        }

let provider = LocalResolutionProvider
        { dataSource      = httpSource
        , fallbackSource  = Nothing  -- optional fallback data source
        , refreshStrategy = Polling $ PollingStrategy { interval = 30, timeout = Just 10 }
        }

-- Initialize the provider (fetches initial config)
initProvider provider defaultEvaluationContext

-- Resolve all features
let context = defaultEvaluationContext
        & withTargetingKey "user-1234"
        & withCustomField "dimension" "d2"

allConfig <- resolveAllFeatures provider context
putStrLn $ "All config: " <> show allConfig

-- Get applicable experiment variants
variants <- getApplicableVariants provider context Nothing
putStrLn $ "Variants: " <> show variants

-- Cleanup
closeProvider provider
```

--------------------------------

### Run local_file_example.py

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Runs the local file configuration loading example with on-demand refresh.

```bash
python local_file_example.py
```

--------------------------------

### Run polling_example.py with defaults

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Runs the polling example with default settings.

```bash
# With defaults
python polling_example.py
```

--------------------------------

### Complete Example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/format-specification.md

A full ride-hailing pricing configuration with default configs, dimensions, and multiple overrides.

```toml
# Ride-hailing pricing configuration

[default-configs]
per_km_rate = { value = 20.0, schema = { type = "number", minimum = 0 } }
surge_factor = { value = 0.0, schema = { type = "number", minimum = 0 } }
base_fare = { value = 50.0, schema = { type = "number", minimum = 0 } }

[dimensions]
city = {
    position = 4,
    schema = { type = "string", enum = ["Chennai", "Bangalore", "Delhi"] }
}
vehicle_type = {
    position = 2,
    schema = { type = "string", enum = ["auto", "cab", "bike"] }
}
hour_of_day = {
    position = 3,
    schema = { type = "integer", minimum = 0, maximum = 23 }
}
city_cohort = {
    position = 1,
    type = "LOCAL_COHORT:city",
    schema = {
        type = "string",
        enum = ["south", "otherwise"],
        definitions = {
            south = { in = [{ var = "city" }, ["Bangalore", "Chennai"]] }
        }
    }
}

# Bike rides are cheaper
[[overrides]]
_context_ = { vehicle_type = "bike" }
per_km_rate = 15.0

# Cab rides have premium pricing
[[overrides]]
_context_ = { vehicle_type = "cab" }
per_km_rate = 25.0

# Bangalore cabs have specific rate
[[overrides]]
_context_ = { city = "Bangalore", vehicle_type = "cab" }
per_km_rate = 22.0

# Early morning surge in Delhi
[[overrides]]
_context_ = { city = "Delhi", vehicle_type = "cab", hour_of_day = 6 }
surge_factor = 5.0

# Evening surge in Delhi
[[overrides]]
_context_ = { city = "Delhi", vehicle_type = "cab", hour_of_day = 18 }
surge_factor = 5.0

# South India cohort pricing
[[overrides]]
_context_ = { city_cohort = "south" }
base_fare = 40.0
```

--------------------------------

### Example Usage in Default Config

Source: https://github.com/juspay/superposition/blob/main/docs/docs/basic-concepts/safety/type-templates.md

TOML example showing how to reference type templates in a default configuration.

```toml
[default-config]
per_km_rate = { "value" = 20.0, "schema" = { "$ref": "#/types/Decimal" } }
user_location = { "value" = {"lat": 0.0, "lng": 0.0}, "schema" = { "$ref": "#/types/GeographicCoordinate" } }
```

--------------------------------

### Install superposition-provider with npm

Source: https://github.com/juspay/superposition/blob/main/clients/javascript/open-feature-provider/README.md

Install the provider package using npm. Requires a running Superposition server before using the client code.

```bash
npm install superposition-provider
```

--------------------------------

### Install Superposition SDK with npm

Source: https://github.com/juspay/superposition/blob/main/clients/javascript/sdk/README.md

Install the Superposition SDK package using npm.

```bash
npm install superposition-sdk
```

--------------------------------

### Install dependencies

Source: https://github.com/juspay/superposition/blob/main/examples/dynamic-payment-fields/README.md

Installs project dependencies using npm.

```bash
npm install
```

--------------------------------

### HELLO.MUL Command Example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/applications/cac-redis-module.md

Utility command that multiplies numbers (example from Redis module template). Returns the input numbers and the product.

```bash
redis-cli> HELLO.MUL 2 3 4
1) (integer) 2
2) (integer) 3
3) (integer) 4
4) (integer) 24
```

--------------------------------

### Start Docker daemon on Linux

Source: https://github.com/juspay/superposition/blob/main/docs/docs/setup.md

Starts the Docker daemon on Linux using systemctl.

```bash
sudo systemctl start docker
```

--------------------------------

### Install Superposition with Helm

Source: https://github.com/juspay/superposition/blob/main/helm/README.md

Installs the Superposition Helm chart into the 'superposition' namespace.

```bash
helm install superposition . -n superposition
```

--------------------------------

### supertoml.start()

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/neovim-extension/README.md

Starts the language server for the SuperTOML Analyzer.

```APIDOC
## supertoml.start()

### Description
Starts the language server for the SuperTOML Analyzer.

### Example
```lua
supertoml.start()
```
```

--------------------------------

### Install Superposition provider with pip

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/README.md

Install the required Python packages: openfeature-sdk and superposition-provider. Ensure Superposition is booted before running client code.

```bash
pip install openfeature-sdk
pip install superposition-provider
```

--------------------------------

### Java Quick Start: Superposition OpenFeature Provider

Source: https://github.com/juspay/superposition/blob/main/docs/docs/providers/openfeature/java.md

This example shows the most common usage: connecting to a Superposition server via HTTP, polling for config updates, and evaluating flags locally. It creates an HttpDataSource with endpoint, token, orgId, and workspaceId, sets up ExperimentationOptions with a polling refresh strategy, builds a LocalResolutionProvider, initializes it with an EvaluationContext, and registers it with OpenFeature. It then evaluates string, integer, and boolean flags, and calls provider-specific methods evaluateConfig and getApplicableVariants.

```java
import dev.openfeature.sdk.*;
import io.juspay.superposition.openfeature.*;
import io.juspay.superposition.openfeature.options.*;

import java.util.List;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        // 1. Create an HTTP data source pointing to your Superposition server
        HttpDataSource httpSource = new HttpDataSource(SuperpositionOptions.builder()
            .endpoint("http://localhost:8080")
            .token("your-api-token")
            .orgId("localorg")
            .workspaceId("test")
            .build());

        // 2. Configure experimentation options
        ExperimentationOptions expOptions = ExperimentationOptions.builder()
            .refreshStrategy(RefreshStrategy.Polling.of(5000, 2000))
            .build();

        // 3. Create the provider with a polling refresh strategy
        LocalResolutionProvider provider = LocalResolutionProvider.builder()
            .dataSource(httpSource)
            .refreshStrategy(RefreshStrategy.Polling.of(10000, 5000))
            .experimentationOptions(expOptions)
            .build();

        // 4. Initialize and register with OpenFeature
        EvaluationContext initCtx =
            new ImmutableContext(Map.of("city", new Value("Berlin")));
        provider.initialize(initCtx);

        OpenFeatureAPI api = OpenFeatureAPI.getInstance();
        api.setProvider(provider);
        Client client = api.getClient();

        // 5. Define evaluation context
        EvaluationContext ctx = new ImmutableContext(
            "user-42",
            Map.of(
                "city", new Value("Berlin"),
                "os", new Value("android")
            )
        );

        // 6. Evaluate feature flags
        String currency = client.getStringValue("currency", "USD", ctx);
        System.out.println("currency = " + currency);

        Integer price = client.getIntegerValue("price", 0, ctx);
        System.out.println("price = " + price);

        boolean darkMode = client.getBooleanValue("dark_mode", false, ctx);
        System.out.println("dark_mode = " + darkMode);

        // 7. Get full resolved config (provider-specific)
        Map<String, Object> fullConfig = provider.evaluateConfig(ctx);
        System.out.println("Full config: " + fullConfig);

        // 8. Get applicable experiment variants (provider-specific)
        List<String> variants = provider.getApplicableVariants(ctx);
        System.out.println("Applicable variants: " + variants);
    }
}
```

--------------------------------

### Default configuration example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/cascading-model.md

Shows the default configuration that serves as the base for all resolution.

```toml
[default-configs]
per_km_rate = { value = 20.0, schema = { type = "number" } }
surge_factor = { value = 0.0, schema = { type = "number" } }
```

--------------------------------

### Install Node.js dependencies

Source: https://github.com/juspay/superposition/blob/main/clients/javascript/bindings/README_TOML_TESTS.md

Installs npm dependencies for the JavaScript bindings. Run from the clients/javascript/bindings directory.

```bash
cd clients/javascript/bindings
npm install
```

--------------------------------

### Simple types example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/format-specification.md

Shows how to define string, number, and boolean configuration keys with their schemas.

```toml
[default-configs]
# String configuration
app_name = { value = "MyApp", schema = { type = "string" } }

# Number configuration
max_connections = { value = 100, schema = { type = "integer", minimum = 1, maximum = 1000 } }

# Boolean configuration
debug_mode = { value = false, schema = { type = "boolean" } }
```

--------------------------------

### Run local_file_watch_example.py

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Runs the file watching example in Terminal 1, and instructs to edit config.toml in Terminal 2. The running example will display updated values within 2 seconds.

```bash
# Terminal 1: Run the example
python local_file_watch_example.py

# Terminal 2: Edit config.toml
# The running example will display updated values within 2 seconds
```

--------------------------------

### Start Experiment (10% traffic)

Source: https://github.com/juspay/superposition/blob/main/docs/docs/applications/k8s-staggered-releaser.md

Webhook triggered automatically by Superposition to start an experiment with 10% traffic. Creates a Deployment, Service, and Ingress with the specified weight.

```bash
# Webhook triggered automatically by Superposition
# Creates:
# - Deployment: nginxservice-dep-variant-123
# - Service: nginxservice-service-variant-123  
# - Ingress: nginxservice-ingress-variant-123 (10% weight)
```

--------------------------------

### Arrays example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/format-specification.md

Shows how to define a configuration key with an array schema.

```toml
[default-configs]
allowed_origins = {
    value = ["https://example.com"],
    schema = {
        type = "array",
        items = { type = "string", format = "uri" },
        minItems = 1
    }
}
```

--------------------------------

### Dimensions Configuration Example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/deterministic-resolution.md

Example TOML configuration defining dimensions with positions and schemas.

```toml
[dimensions]
city = { position = 4, schema = { type = "string" } }
vehicle_type = { position = 2, schema = { type = "string" } }
hour_of_day = { position = 3, schema = { type = "integer" } }
```

--------------------------------

### Install dependencies with yarn

Source: https://github.com/juspay/superposition/blob/main/docs/README.md

Run this command in the project root to install all required dependencies for the Docusaurus website.

```bash
yarn
```

--------------------------------

### Run local_http_example.py

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Runs the HTTP polling example that fetches configuration from Superposition API at http://localhost:8080.

```bash
python local_http_example.py
```

--------------------------------

### Bash: Start the binary with make run

Source: https://github.com/juspay/superposition/blob/main/docs/superpowers/plans/2026-05-10-otel-golden-signals-middleware.md

Starts the binary against the local docker-compose dev stack. The makefile target may vary; adjust as needed.

```bash
make run    # or whatever the makefile target is
```

--------------------------------

### Install dependencies on MacOS

Source: https://github.com/juspay/superposition/blob/main/docs/docs/setup.md

Installs required libraries and tools (libpq, openssl, libiconv, awscli, yq) using Homebrew.

```bash
brew install libpq openssl libiconv awscli yq
```

--------------------------------

### config.get_init_options()

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/neovim-extension/README.md

Gets the initialization options from the config submodule.

```APIDOC
## config.get_init_options()

### Description
Gets the initialization options from the config submodule.

### Returns
- **table** - Initialization options.

### Example
```lua
local init_opts = config.get_init_options()
```
```

--------------------------------

### Compile and run the app with make superposition-example

Source: https://github.com/juspay/superposition/blob/main/examples/superposition-demo-app/README.md

Run this command in the project root to compile and launch the demo app. It is the only setup step shown.

```sh
make superposition-example
```

--------------------------------

### Runtime context example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/cascading-model.md

Shows a sample runtime context used to find matching overrides.

```json
{ "city": "Bangalore", "vehicle_type": "cab", "hour_of_day": 18 }
```

--------------------------------

### Enum values example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/format-specification.md

Shows how to define a configuration key with an enum schema.

```toml
[default-configs]
log_level = {
    value = "info",
    schema = {
        type = "string",
        enum = ["debug", "info", "warn", "error"]
    }
}
```

--------------------------------

### Example context provided by the application

Source: https://github.com/juspay/superposition/blob/main/docs/docs/basic-concepts/context-aware-config/how-all-this-works.mdx

This JSON object shows the context that the application provides to the client for evaluation, using the ride-hailing example with city, vehicle_type, and hour_of_day.

```json
{
    "city": "Delhi", 
    "vehicle_type": "cab", 
    "hour_of_day": 19
}
```

--------------------------------

### Start Neovim with the plugin

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/neovim-extension/README.md

Launch Neovim with the plugin's runtime path added via the --cmd flag.

```bash
nvim --cmd "set rtp+=/path/to/superposition/tooling/lsp/neovim-extension"
```

--------------------------------

### Run the webhook server with cargo run

Source: https://github.com/juspay/superposition/blob/main/docs/docs/applications/k8s-staggered-releaser.md

Starts the server, which listens on 127.0.0.1:8090 for webhook events at /hi.

```bash
cargo run
```

--------------------------------

### Run local_with_fallback_example.py

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Runs the primary and fallback sources example, using HTTP primary and local file fallback.

```bash
python local_with_fallback_example.py
```

--------------------------------

### Java example: Initialize Superposition provider and evaluate flags

Source: https://github.com/juspay/superposition/blob/main/clients/java/openfeature-provider/README.md

Shows how to configure experimentation options, build provider options, initialize the provider, set it on the OpenFeature API, and evaluate a boolean flag, the full configuration, and applicable variants.

```java
import dev.openfeature.sdk.*;
import io.juspay.superposition.openfeature.*;
import io.juspay.superposition.openfeature.options.RefreshStrategy;

import java.util.List;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        // Configure experimentation options
        SuperpositionProviderOptions.ExperimentationOptions expOptions =
            SuperpositionProviderOptions.ExperimentationOptions.builder()
                .refreshStrategy(RefreshStrategy.Polling.of(5000, 2000)) // 5s timeout, 2s interval
                .build();

        // Configure provider options
        SuperpositionProviderOptions options =
            SuperpositionProviderOptions.builder()
                .orgId("your-org-id")
                .workspaceId("your-workspace-id")
                .endpoint("https://api.superposition.dev")
                .token("your-api-token")
                .refreshStrategy(RefreshStrategy.Polling.of(10000, 5000)) // 10s timeout, 5s interval
                .experimentationOptions(expOptions)
                .build();

        // Initialize provider
        SuperpositionOpenFeatureProvider provider =
            new SuperpositionOpenFeatureProvider(options);
        EvaluationContext initCtx =
            new ImmutableContext(Map.of("foo", new Value("bar")));
        provider.initialize(initCtx);
        OpenFeatureAPI.getInstance().setProvider(provider);
        Client client = OpenFeatureAPI.getInstance().getClient();

        // Create evaluation context (optional)
        EvaluationContext ctx =
            new ImmutableContext(Map.of("userId", new Value("123")));

        // Evaluate a boolean flag
        boolean enabled = client.getBooleanValue("my-feature-flag", false, ctx);
        System.out.println("Feature enabled: " + enabled);


        // Evaluate & get the entire configuration
        System.out.println("Full config: " + provider.evaluateConfig(ctx));

        // Get the applicable variants for the ongoing experiments
        EvaluationContext experimentCtx = new ImmutableContext("your-targeting-key", Map.of("userId", new Value("123")));
        List<String> variants = provider.applicableVariants(experimentCtx);
        System.out.println("Variants: " + variants);
    }
}
```

--------------------------------

### Arrays Example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/type-safety.md

Illustrates array schemas with item types, unique items, and length bounds.

```toml
[default-configs]
# Array of strings
allowed_hosts = {
    value = ["localhost", "example.com"],
    schema = {
        type = "array",
        items = { type = "string" },
        minItems = 1
    }
}

# Array with unique items
tags = {
    value = ["production", "critical"],
    schema = {
        type = "array",
        items = { type = "string" },
        uniqueItems = true
    }
}

# Array with length bounds
features = {
    value = ["feature_a", "feature_b"],
    schema = {
        type = "array",
        items = { type = "string" },
        minItems = 0,
        maxItems = 10
    }
}
```

--------------------------------

### Matching overrides example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/cascading-model.md

Shows overrides that match the runtime context, with checkmarks for matches and crosses for non-matches.

```toml
# ✅ Matches (vehicle_type matches)
[[overrides]]
_context_ = { vehicle_type = "cab" }
per_km_rate = 25.0

# ✅ Matches (city AND vehicle_type match)
[[overrides]]
_context_ = { city = "Bangalore", vehicle_type = "cab" }
per_km_rate = 22.0

# ✅ Matches (all three match)
[[overrides]]
_context_ = { city = "Bangalore", vehicle_type = "cab", hour_of_day = 18 }
surge_factor = 5.0

# ❌ Does NOT match (city is different)
[[overrides]]
_context_ = { city = "Delhi", vehicle_type = "cab" }
per_km_rate = 28.0

# ❌ Does NOT match (hour_of_day is different)
[[overrides]]
_context_ = { hour_of_day = 6 }
surge_factor = 3.0
```

--------------------------------

### Install diesel_cli with cargo

Source: https://github.com/juspay/superposition/blob/main/docs/docs/setup.md

Installs diesel_cli with postgres feature using cargo.

```bash
cargo install diesel_cli --no-default-features --features postgres
```

--------------------------------

### Start Docker daemon on MacOS

Source: https://github.com/juspay/superposition/blob/main/docs/docs/setup.md

Starts Docker Desktop on MacOS in the background.

```bash
open --background -a Docker
```

--------------------------------

### Basic Development Setup (values.yaml)

Source: https://github.com/juspay/superposition/blob/main/helm/README.md

Minimal configuration for local development. Sets replica count to 1, uses a local PostgreSQL database, disables authentication, and exposes the service via ClusterIP on port 80.

```yaml
replicaCount: 1

configs:
  database_url: postgres://postgres:docker@postgres:5432/config?sslmode=disable
  port: 8080
  rust_log: debug
  app_env: DEV
  auth_provider: DISABLED

secrets:
  db_password: "docker"

service:
  type: ClusterIP
  port: 80

```

--------------------------------

### Run polling_example.py with full custom configuration

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Runs the polling example with a fully custom configuration using exported environment variables.

```bash
# Full custom configuration
export SUPERPOSITION_ENDPOINT="http://my-server:8080"
export SUPERPOSITION_ORG_ID="myorg"
export SUPERPOSITION_WORKSPACE="production"
python polling_example.py
```

--------------------------------

### Get Specific Webhook - GET /webhook/{webhook_name}

Source: https://github.com/juspay/superposition/blob/main/docs/docs/basic-concepts/experimentation/experiments.mdx

Retrieves details of a specific webhook by its name.

```bash
GET /webhook/{webhook_name}
```

--------------------------------

### Preview production build

Source: https://github.com/juspay/superposition/blob/main/examples/dynamic-payment-fields/README.md

Serves the production build locally for preview.

```bash
npm run preview
```

--------------------------------

### Install extension dependencies

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/vscode-extension/README.md

Navigate to the vscode-extension directory and install npm dependencies. This is required before compiling the extension.

```bash
cd tooling/lsp/vscode-extension
npm install
```

--------------------------------

### Run polling_example.py with custom settings

Source: https://github.com/juspay/superposition/blob/main/clients/python/provider/examples/README.md

Runs the polling example with custom environment variables for poll interval, print interval, and config key.

```bash
# With custom settings
POLL_INTERVAL=5 PRINT_INTERVAL=3 CONFIG_KEY=timeout python polling_example.py
```

--------------------------------

### List default configs asynchronously

Source: https://github.com/juspay/superposition/blob/main/clients/python/sdk/README.md

Example of using the SDK to list default configs. It creates a client, builds a ListDefaultConfigsInput with workspace and org IDs, calls list_default_configs, and prints the response.

```python
import asyncio
from superposition_sdk.client import Config, ListDefaultConfigsInput, Superposition
from pprint import pprint

async def list_configs():
    client = Superposition(Config(endpoint_uri="http://localhost:8080"))
    list_configs = ListDefaultConfigsInput(workspace_id="upi", org_id="orgid162145664241766405", all=True)
    response = await client.list_default_configs(list_configs)
    pprint(response)

asyncio.run(list_configs())
```

--------------------------------

### supertoml.setup(config)

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/neovim-extension/README.md

Sets up the SuperTOML Analyzer plugin with the provided configuration table.

```APIDOC
## supertoml.setup(config)

### Description
Sets up the SuperTOML Analyzer plugin with the provided configuration table.

### Parameters
- **config** (table) - Required - Configuration table for the plugin.

### Example
```lua
supertoml.setup({ /* config */ })
```
```

--------------------------------

### Get Webhooks by Event - GET /webhook/event/{event_type}

Source: https://github.com/juspay/superposition/blob/main/docs/docs/basic-concepts/experimentation/experiments.mdx

Fetches webhooks associated with a specific event type.

```bash
GET /webhook/event/{event_type}
```

--------------------------------

### Configure Multi-Tenant Support in main.rs

Source: https://github.com/juspay/superposition/blob/main/docs/docs/applications/k8s-staggered-releaser.md

Sets up the application state with lists of namespaces and tenants for multi-tenant support. Configure this in main.rs.

```rust
let app_state = Data::new(AppState {
    namespaces: ["mumbai".to_string(), "delhi".to_string()].to_vec(),
    tenants: ["service1".to_string(), "service2".to_string()].to_vec(),
});
```

--------------------------------

### LocalResolutionProvider setup and usage

Source: https://github.com/juspay/superposition/blob/main/docs/docs/providers/openfeature/python.md

Initializes a LocalResolutionProvider with an HttpDataSource, polling refresh strategy, and experimentation options. Demonstrates async initialization, resolving all config details, and shutdown. Requires an endpoint, token, org_id, and workspace_id.

```python
from superposition_provider import (
    LocalResolutionProvider,
    HttpDataSource,
    SuperpositionOptions,
    PollingStrategy,
    RefreshStrategy,
    ExperimentationOptions,
    EvaluationCacheOptions,
)
from openfeature.evaluation_context import EvaluationContext

http_source = HttpDataSource(SuperpositionOptions(
    endpoint="http://localhost:8080",
    token="token",
    org_id="localorg",
    workspace_id="dev",
))

provider = LocalResolutionProvider(
    data_source=http_source,
    fallback_source=None,
    refresh_strategy=RefreshStrategy.Polling(PollingStrategy(interval=30, timeout=10)),
    experimentation_options=ExperimentationOptions(
        refresh_strategy=RefreshStrategy.Polling(PollingStrategy(interval=5, timeout=3)),
        evaluation_cache=EvaluationCacheOptions(ttl=300, size=1000),
        default_toss=50,
    ),
)

# Initialize the provider (fetches initial config)
await provider.initialize(context=EvaluationContext())

# Resolve all config values at once
ctx = EvaluationContext(
    targeting_key="user-1234",
    attributes={"city": "Berlin", "os": "android"},
)
all_config = provider.resolve_all_config_details({}, ctx)
print(f"All config: {all_config}")

# Cleanup
await provider.shutdown()
```

--------------------------------

### Example Webhook Payload for ExperimentConcluded Event

Source: https://github.com/juspay/superposition/blob/main/docs/docs/basic-concepts/experimentation/experiments.mdx

Example payload for the ExperimentConcluded event, showing the chosen variant and final status.

```json
{
  "event_info": {
    "webhook_event": "ExperimentConcluded",
    "time": "2024-12-24T15:45:00Z",
    "workspace_id": "ecommerce",
    "organisation_id": "mycompany"
  },
  "payload": {
    "id": 123456789,
    "name": "checkout-optimization",
    "chosen_variant": "experimental-variant",
    "variants": [
      {
        "id": "control-variant",
        "variant_type": "CONTROL"
      },
      {
        "id": "experimental-variant",
        "variant_type": "EXPERIMENTAL"
      }
    ],
    "status": "CONCLUDED"
  }
}
```

--------------------------------

### Install Xcode command line tools on MacOS

Source: https://github.com/juspay/superposition/blob/main/docs/docs/setup.md

Installs Xcode command line tools on MacOS to ensure make is available.

```bash
xcode-select --install
```

--------------------------------

### List default configs using ListDefaultConfigsCommand

Source: https://github.com/juspay/superposition/blob/main/clients/javascript/sdk/README.md

Example of using the SDK to list default configs. Requires workspace_id and org_id.

```javascript
import { SuperpositionClient, ListDefaultConfigsCommand } from "superposition-sdk";

let config = {
    endpoint: "http://localhost:8080",
    token: {
        token: "your-token-here",
    },
};
let client = new SuperpositionClient(config);

let list_default_configs = async (client) => {
    const cmd = new ListDefaultConfigsCommand({
        workspace_id: "workspace_id",
        org_id: "organisation_id",
    });
    let response = await client.send(cmd);
    console.log(JSON.stringify(response.data));
};

await list_default_configs(client);
```

--------------------------------

### Build LSP server in development mode

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/vscode-extension/README.md

Navigate to the superposition repository and build the supertoml_lsp package. This is the first step of the development mode installation.

```bash
cd /path/to/superposition
cargo build -p supertoml_lsp
```

--------------------------------

### Start Redis with the module loaded

Source: https://github.com/juspay/superposition/blob/main/docs/docs/applications/cac-redis-module.md

Starts a Redis server with the CAC Redis module loaded using the --loadmodule flag.

```bash
redis-server --loadmodule ./target/release/libredis_module_cac.so
```

--------------------------------

### GET /config/resolve endpoint request

Source: https://github.com/juspay/superposition/blob/main/docs/docs/applications/k8s-staggered-releaser.md

HTTP GET request to fetch deployment configurations from Superposition, requiring x-org-id and x-tenant headers.

```text
GET /config/resolve?namespace={namespace}&variantIds={variant_id}
Headers:
  x-org-id: localorg
  x-tenant: {service_name}
```

--------------------------------

### Python: Basic authentication with auth_helpers

Source: https://github.com/juspay/superposition/blob/main/clients/python/sdk/AUTH_README.md

Shows how to configure basic authentication using `basic_auth_config` from `auth_helpers.py`, create a `Config` with the resolver and schemes, and instantiate the client.

```python
from superposition_sdk.auth_helpers import basic_auth_config
from superposition_sdk.client import Superposition
from superposition_sdk.config import Config

# Get basic auth config
(resolver, schemes) = basic_auth_config(username="user", password="pass")

# Create config
config = Config(
    endpoint_uri="https://api.example.com",
    http_auth_scheme_resolver=resolver,
    http_auth_schemes=schemes
)

# Create client
client = Superposition(config)
```

--------------------------------

### String Constraints Example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/type-safety.md

Shows how to apply string constraints: format for email, pattern matching for API keys, and length constraints for descriptions.

```toml
[default-configs]
# Email format
admin_email = {
    value = "admin@example.com",
    schema = { type = "string", format = "email" }
}

# Pattern matching
api_key = {
    value = "sk_test_1234567890",
    schema = { type = "string", pattern = "^sk_[a-z]+_[a-zA-Z0-9]+$" }
}

# Length constraints
description = {
    value = "A short description",
    schema = { type = "string", minLength = 10, maxLength = 500 }
}
```

--------------------------------

### Basic Configuration Resolution Examples

Source: https://github.com/juspay/superposition/blob/main/docs/docs/applications/cac-redis-module.md

Shows CAC.EVAL queries with matching and non-matching contexts. The first query matches a condition, the second does not.

```bash
# Query with context that matches a condition
redis-cli> CAC.EVAL '{"d1": "d1"}'

# Query with context that doesn't match any condition
redis-cli> CAC.EVAL '{"unknown": "value"}'
```

--------------------------------

### Start the stack and check health

Source: https://github.com/juspay/superposition/blob/main/docs/docs/deployment.md

Commands to start the Docker Compose stack and verify the health endpoint. The curl command expects the response 'Health is good :D'.

```bash
docker compose up -d
curl http://localhost:8080/health
```

--------------------------------

### Example Webhook Payload for ExperimentStarted Event

Source: https://github.com/juspay/superposition/blob/main/docs/docs/basic-concepts/experimentation/experiments.mdx

Example payload for the ExperimentStarted event, showing the event_info and payload with experiment details such as context, variants, and traffic percentage.

```json
{
  "event_info": {
    "webhook_event": "ExperimentStarted",
    "time": "2024-12-24T10:30:00Z",
    "workspace_id": "ecommerce",
    "organisation_id": "mycompany"
  },
  "payload": {
    "id": 123456789,
    "name": "checkout-optimization",
    "context": {
      "and": [
        {"==": [{"var": "region"}, "north"]},
        {"==": [{"var": "user_type"}, "premium"]}
      ]
    },
    "variants": [
      {
        "id": "control-variant",
        "variant_type": "CONTROL"
      },
      {
        "id": "experimental-variant",
        "variant_type": "EXPERIMENTAL"
      }
    ],
    "traffic_percentage": 10,
    "status": "INPROGRESS"
  }
}
```

--------------------------------

### Avoid Overlapping Cohort Conditions

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/dimensions.md

Shows a bad example with overlapping conditions and a good example with mutually exclusive conditions. Overlapping conditions create ambiguity about which cohort wins.

```toml
# ❌ Bad: Overlapping conditions - which wins?
definitions = {
    south = { in = [{ var = "city" }, ["Bangalore", "Chennai", "Delhi"]] },
    north = { in = [{ var = "city" }, ["Delhi", "Mumbai"]] }
}

# ✅ Good: Mutually exclusive conditions
definitions = {
    south = { in = [{ var = "city" }, ["Bangalore", "Chennai"]] },
    north = { in = [{ var = "city" }, ["Delhi", "Mumbai"]] }
}
```

--------------------------------

### Example: Check if hour_of_day >= 18

Source: https://github.com/juspay/superposition/blob/main/docs/docs/superposition-config-file/context-expressions.md

This example shows how to check if the hour_of_day dimension is greater than or equal to 18 using the ">=" operator and the "var" operator.

```text
{">=": [{"var": "hour_of_day"}, 18]}
```

--------------------------------

### Package the extension into a VSIX

Source: https://github.com/juspay/superposition/blob/main/tooling/lsp/vscode-extension/README.md

Install dependencies, compile, and package the extension. This creates a .vsix file in the current directory.

```bash
cd tooling/lsp/vscode-extension
npm install
npm run compile
npm run package
```

--------------------------------

### CAC.HELLO Command Example

Source: https://github.com/juspay/superposition/blob/main/docs/docs/applications/cac-redis-module.md

Simple greeting command for testing module functionality. Returns a greeting message with the provided argument.

```bash
redis-cli> CAC.HELLO "World"
"Hello from CAC module, World!"
```

--------------------------------

### Get application URL via NodePort service

Source: https://github.com/juspay/superposition/blob/main/helm/templates/NOTES.txt

When the service type contains 'NodePort', this template outputs commands to get the node port and node IP, then prints the application URL.

```helm
  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "superposition.fullname" . }})
  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
  echo http://$NODE_IP:$NODE_PORT
```

--------------------------------

### Configuration Context Example

Source: https://github.com/juspay/superposition/blob/main/examples/dynamic-payment-fields/README.md

Sample configuration object defining the payment context with connector, payment method, and other attributes. Used to determine the appropriate form fields.

```javascript
{
  connector: "stripe",
  payment_method: "card",
  payment_method_type: "credit",
  country: "US",
  mandate_type: "non_mandate",
  collect_billing_details_from_wallet_connector: "false",
  collect_shipping_details_from_wallet_connector: "false"
}
```

--------------------------------

### Clone the repository

Source: https://github.com/juspay/superposition/blob/main/examples/dynamic-payment-fields/README.md

Clones the demo repository and navigates into the project directory.

```bash
git clone git@github.com:sh-iv-am/superposition-hyperswitch-demo.git
cd superposition-hyperswitch-demo
```
Tokens:
Raw