How did it all start?​

There were many applications in Juspay that needed runtime configuration management systems. Many systems relied on JSON files deployed on S3. There were just too many issues in this model of serving configuration files. No problem-modelling of the configuration values, no tooling to safely edit and roll out those changes in a safe manner and challenges in keeping multiple files updated at scale. Some of these configuration changes were the cause of production outages as well. Superposition started off as a system to address this use-case.

Safety first​

With safety being a top priority, we anchored on the following three core principles:

1. Safely change configuration values at runtime, supporting the following:
   1. Type safety
   2. Custom validations
   3. Staggered roll-out

If our system could factor in the above - we would have done well.

Safety aside, another salient requirement in our applications was that under some defined domain context - the configurations took a different value i.e. in other words the value needs to be overridden under some conditions. This was either managed with control blocks in code (simple if-else statements) or by suffixing/prefixing the key with a string that represents the context and defining a new row for that key with the overridden value. For e.g. if a configuration was called notification_enabled with a default value of false and we had to enable it only for say iOS users, one would create a key called iOS_notification_enabled and set it to true. In most cases, when no override exists for a specific context, the typical expectation is to fallback to a default value. This approach doesn't scale well once the configuration started to depend on multiple contexts as managing the ordering of the suffixes gets complicated.

Cascading configurations​

We added this as one of the core problems that the new configuration system should address as we felt it was too important a feature for a configuration system to ignore.

1. Safely change configuration values at runtime, supporting the following:
   1. Type safety
   2. Custom validations
   3. Staggered roll-out
2. Cascading configuration values

Once we decided to support cascading configuration values, we had to solve for how to formally define contexts under which configuration values could change.

And so we decided to model the concept of contexts. Contexts are simple boolean expressions involving key attributes that matter to your domain. We chose to call these key attributes dimensions. Dimensions are also defined with their associated types to ensure that values set for dimensions in contexts are validated and type-safe.

To illustrate the above, we will use the TOML representation of Superposition configurations. Let us say your application is available across Android, iOS and Web - you might want to create a dimension which is an enum holding one of three possible values: ios, android and web. Below is an example that shows a configuration key having a default value under a section title default-config, but having an override when platform is web. Note the definition of the types for the values of the default-config and dimensions to support our type-safety requirement.

[default-config]
notification_enabled = { "value" = false, "schema" = { "type" = "boolean" } }

[dimensions]
platform = { schema = { "type" = "string", "enum" = ["ios", "android", "web"] } }

[[overrides]]
_context_ = { platform = "web" }
notification_enabled = true

Disambiguating conflicting contexts​

Now let us say your application needs to disable notifications when users use the Edge browser. To facilitate this override, you would create a new dimension called browser with the following as possible values: ["chrome", "safari", "edge", "arc", "brave"] and add a corresponding override section with a context using the newly added browser dimension.

[default-config]
notification_enabled = { "value" = false, "schema" = { "type" = "boolean" } }

[dimensions]
platform = { schema = { "type" = "string", "enum" = ["ios", "android", "web"] } }
browser = { schema = { "type" = "string", "enum" = ["chrome", "safari", "edge", "arc", "brave"] } }

[[overrides]]
_context_ = { platform = "web" }
notification_enabled = true

[[overrides]]
_context_ = { browser = "edge" }
notification_enabled = false

To the astute observer, it will become apparent that we have landed ourselves in a bit of a soup - if someone accesses your application over the web from an edge browser both the contexts evaluate to true. So which configuration should apply? The easiest choice would have been to decide that latest one applies. The latest-one-wins approach brings with it a couple of key challenges:

• Firstly, it brings in a lack of predictability when multiple people can modify configurations and might not share the same idea of prioritizing the overrides.
• Secondly, the latest wins approach does not scale well when the number of the overrides grow - it is very hard to manage relative priority of the overrides even at a small cardinality of 10s of overrides and becomes error-prone.

Such an approach fundamentally affects the core requirement of the configuration system - safety. To address this, we decided to force the user to tie-break between the dimensions i.e. explicitly decide their priority depending on their domain contexts. While this choice might seem constraining - we believe it brings in the clarity and communicates clearly to all users of the configuration system what the relative priorities are. It makes it easy to author an override without worrying about where to place the override. We also believe at a deeper level most systems end-up having an implicit priority between these dimensions in code if it is not explicitly stated or captured.

So we refined the definition of what we wanted to build. We wanted to build a configuration system that would enable the following:

1. Safely change configuration values at runtime, supporting the following:
   1. Type safety
   2. Custom validations
   3. Staggered roll-out
2. Unambiguous cascading of configuration values

Now we enhance our earlier example to explicitly tie-break between the dimensions using a field called position in the definition of the dimension. Higher the position, higher the weightage for that dimension. So in the following example the override with the browser context check triumphs even though it appears before the one with the platform context.

[default-config]
notification_enabled = { "value" = false, "schema" = { "type" = "boolean" } }

[dimensions]
platform = { position = 1, schema = { "type" = "string", "enum" = ["ios", "android", "web"] } }
browser = { position = 2, schema = { "type" = "string", "enum" = ["chrome", "safari", "edge", "arc", "brave"] } }

[[overrides]]
_context_ = { browser = "edge" }
notification_enabled = false

[[overrides]]
_context_ = { platform = "web" }
notification_enabled = true

Cascading configurations and staggering the change​

As we did this - we noticed an interesting nexus between cascading configurations and the need to be able to stagger configuration changes. Staggering of configuration changes can be treated as an experimental override if we capture the experimental variation as part of the context. Hence, the cascading nature of the configuration was not just an independent requirement, it also formed the basis for supporting configuration staggering. To illustrate this, let us say we want to enable notifications for the edge browser - but stagger the change.

[default-config]
notification_enabled = { "value" = false, "schema" = { "type" = "boolean" } }

[dimensions]
bucket = { position = 1, schema = { "type" = "string" } }
platform = { position = 2, schema = { "type" = "string", "enum" = ["ios", "android", "web"] } }
browser = { position = 3, schema = { "type" = "string", "enum" = ["chrome", "safari", "edge", "arc", "brave"] } }

[[overrides]]
_context_ = { browser = "edge" }
notification_enabled = false

[[overrides]]
_context_ = { platform = "web" }
notification_enabled = true

[[overrides]]
_context_ = { browser = "edge", bucket="old"} # acts as the control bucket for the configuration change
notification_enabled = false

[[overrides]]
_context_ = { browser = "edge", bucket="new"} # acts as the experimental variant for the configuration change
notification_enabled = true

Note: In the above example - when a particular flow is assigned to the new bucket vs the old is not dictated by the core configuration system. It is typically done by an experimentation assignment system while finally delegating the configuration resolution to the core configuration system.

We finalized the above to be the core of our configuration system and it has served us well.

Inspiration​

We would be failing in our duty if we do not call out pieces of technology from where we drew our inspiration to build Superposition:

1. Yahoo Configuration Bundles (for the concept of dimensions/overrides)
2. Cascading Style Sheets (for the concept of specificity)

P.S.​

While we illustrated the core capabilities of Superposition using a TOML representation above, for a full-fledged cloud application, Superposition is available as a deployable service. See the setup instructions to get it running. We will get into the architecture of the Superposition service in a following post.

Superposition is a context-aware configuration management system that ensures correct, safe, and reliable config changes. One of the ways we've achieved this goal is by using jsonschema types for all configuration values with a default value. We call this concept Default Configs. We soon realized an issue - though the type is right, that does not guarantee the correctness of the actual value.

Take the following configuration:

{
    "image_url": "https://example.com/image/cat.png"
}

The strictest JSON schema for the value of image_url would be:

{
  "type": "string",
  "pattern": "^https?:\\/\\/(www\\.)?[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b([-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
}

This schema validates the type and shape and that is one part of correctness, but we're missing the most critical aspect - does the URL exist? Does it return what we're expecting?

User Defined Validation Functions!

We introduced Functions - a way for any end user to write validation logic and link them to a Default Config or Dimension to ensure the correctness of that value (should they want to do that). These functions are written in our frontend monaco editor and saved to a database with some other information. The function looks like this:

async function execute(payload) {
  return true; // boolean
}

If the function returns false, the value being set is invalid and Superposition will not allow it to be saved as a configuration change.

First implementation - Node.js Isolates

Since we just needed a boolean return value, we wrapped the user code with Isolates and ran it as a Node.js script. If the function returned false, the code forced the script to terminate with a custom exit code. When this was run through Rust's std::process::Command, we checked the exit code and interpreted the return value of the function. Users also asked for logs, so console.log would output to stdout, which was also parsed and returned to the user. Running under Node.js let us install npm packages (e.g. axios for HTTP) and use it alongside the script we were running.

When a function is being edited/created, we also ensured that the function the user provided is valid.

This was a simple solution we tried initially and it worked well - until users wanted more capabilities. One capability was Value Compute Functions - functions that returned a vector of values. Users wanted to select a value from a dynamic list of potential values, fetched from internal systems at Juspay, that changes frequently. Another downside to our Node.js isolate solution was a lot of wrapper code to ensure that we properly isolated user code. We didn't validate if the code that was being stored was valid syntactically, and if Node.js could not execute it, we didn't return that error to the user.

Other options

The team had previously looked into mlua, which we decided to not pursue since Superposition users were more familiar with Javascript and looked at ways to run Javascript from within Rust to have better interoperability. Two options we considered were rquickjs and Rustyscript; we went with Rustyscript because of its documentation, features, and better compatibility with Node.js.

Running Javascript in Rust with Rustyscript

Rustyscript is powerful and extremely customizable for running user code - it has a permissions model, functions that you can expose from Rust to use in JS land, and some very nice built-in functionality like console, crypto, http, etc.

Here's a function that validates a URL by fetching it and checking that the response status is 200:

async function execute(payload) {
    const { value_validate } = payload;
    // value_validate is an object that contains all arguments a validation function would need
    const { key, value, type, environment } = value_validate; 
    let response = await fetch(value);
    return response.status === 200;
}

All functions in Superposition are named execute. This is because, while validating the user input, we wrap this code with some helpers and the final code that is passed to Rustyscript looks like:

// wrapper code
let logBuffer = [];
const originalConsole = console;
const customConsole = {
    log: (...args) => {
        logBuffer.push("[log] " + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' '));
    },
    info: (...args) => {
        logBuffer.push("[info] " + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' '));
    },
    warn: (...args) => {
        logBuffer.push("[warn] " + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' '));
    },
    error: (...args) => {
        logBuffer.push("[error] " + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' '));
    },
    debug: (...args) => {
        logBuffer.push("[debug] " + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' '));
    }
};

Object.defineProperty(globalThis, 'console', {
    value: customConsole,
    writable: false,
    configurable: false
});

function getLogBuffer() {
    return logBuffer;
}

function clearLogBuffer() {
    logBuffer = [];
}

// actual user function
async function execute(payload) {
    const { value_validate } = payload;
    // value_validate is an object that contains all arguments a validation function would need
    const { key, value, type, environment } = value_validate; 
    let response = await fetch(value);
    return response.status === 200;
}

export { execute, getLogBuffer, clearLogBuffer };

Note the console override — it routes every log call into an in-memory buffer that we expose via getLogBuffer.

We validate the syntax of the above Javascript with rustyscript::validate, which takes a string and tells you if it is valid syntax or not. If it is not valid, we return an error to the user. This is done before we even try to run the function:

rustyscript::validate(&type_check_code).map_err(|err| {
    log::error!("Invalid function syntax: {:?}", err);
    bad_argument!("Invalid function syntax: {}", err)
})?;

This validates the syntax, but is execute a function and does it return a value that Superposition expects from this category of function? With rustyscript, we can simply just run the function with some default inputs and inspect its return value. This checks:

• execute exists
• execute is a function
• execute returns a value of the expected type (boolean for validation functions, array for value-compute functions)
• the function has handled potential null/undefined values correctly

To run a function in Rustyscript we need to:

• Create a basic runtime
• Load a Javascript module
• Call a function and consume the resulting value as a Rust type

let type_check_code = generate_wrapped_code(&stubbed_code);

rustyscript::validate(&type_check_code).map_err(|err| {
    log::error!("Invalid function syntax: {:?}", err);
    bad_argument!("Invalid function syntax: {}", err)
})?;

let module = Module::new("type_check.js", &type_check_code);
let runtime_options = RuntimeOptions {
    timeout: Duration::from_millis(1500),
    ..Default::default()
};

let mut runtime = Runtime::new(runtime_options).map_err(|e| {
    let err_str = e.to_string();
    validation_error!("Failed to create runtime: {}", err_str)
})?;

let module_handle = runtime.load_module(&module).map_err(|e| {
    let err_str = e.to_string();
    validation_error!("Failed to load module: {}", err_str)
})?;

let tokio_runtime = runtime.tokio_runtime();
tokio_runtime
    .block_on(async {
        let environment = FunctionEnvironment {
            context: serde_json::Map::new(),
            overrides: serde_json::Map::new(),
        };
        match fn_type {
            FunctionType::ValueCompute => {
                let payload = FunctionExecutionRequest::ValueComputeFunctionRequest {
                    name: String::new(),
                    prefix: String::new(),
                    r#type: superposition_types::api::functions::KeyType::ConfigKey,
                    environment,
                };
                let serde_json::Value::Array(_) = runtime
                    .call_function_async::<serde_json::Value>(
                        Some(&module_handle),
                        "execute",
                        json_args!(payload),
                    )
                    .await? else {
                        return Err(rustyscript::Error::Runtime("The value compute function did not return an array".to_string()));
                    };
                Ok(())
            }
            other => {
                let payload = match other {
                    FunctionType::ValueValidation => FunctionExecutionRequest::ValueValidationFunctionRequest {
                        key: String::new(),
                        value: serde_json::Value::String(String::new()),
                        r#type:
                            KeyType::ConfigKey,
                        environment,
                    },
                    FunctionType::ContextValidation => FunctionExecutionRequest::ContextValidationFunctionRequest {
                        environment,
                        trigger_reason: ContextValidationTrigger::Context,
                    },
                    FunctionType::ChangeReasonValidation => FunctionExecutionRequest::ChangeReasonValidationFunctionRequest {
                        change_reason: ChangeReason::default(),
                    },
                    _ => {
                        return Err(rustyscript::Error::Runtime("An invalid situation occurred in the runtime".to_string()))
                    }
                };
                let serde_json::Value::Bool(_) = runtime
                    .call_function_async::<serde_json::Value>(
                        Some(&module_handle),
                        "execute",
                        json_args!(payload),
                    )
                    .await? else {
                        return Err(rustyscript::Error::Runtime("The function did not return a boolean".to_string()))
                    };
                Ok(())
            }

        }
    })
    .map_err(|e| {
        let err_str = e.to_string();
        validation_error!("Function validation failed: {}", err_str)
    })?;

Now when this function needs to be run to validate any input or change, it is run with actual inputs that the system infers based on context. This context could be derived or explicitly stated by the user.

When running this function with user inputs, we use the same code as above, but instead of using a stubbed payload, we use the actual payload that is being validated. The code looks like this:

// wrap user function with code shown above
let wrapped_code = generate_wrapped_code(&code.0); 
let module = Module::new("function.js", &wrapped_code);

let runtime_options = RuntimeOptions {
    timeout: Duration::from_millis(1500),
    ..Default::default()
};

let mut runtime = Runtime::new(runtime_options).map_err(|e| {
    let err_str = e.to_string();
    (format!("Failed to create runtime: {}", err_str), None)
})?;

let payload = FunctionPayload {
    version: runtime_version,
    payload: args.clone(),
};
let module_handle = runtime
    .load_module(&module)
    .map_err(|err| (err.to_string(), None))?;

let tokio_runtime = runtime.tokio_runtime();
// execute function, fn_output takes the value of Value::Bool for the example
let fn_output = tokio_runtime
    .block_on(async {
        runtime
            .call_function_async::<serde_json::Value>(
                Some(&module_handle),
                "execute",
                json_args!(payload),
            )
            .await
    })
    .map_err(|err| (err.to_string(), None))?;

// get logs
let stdout = runtime
    .call_function::<Vec<String>>(Some(&module_handle), "getLogBuffer", json_args!())
    .map_err(|err| (err.to_string(), None))?
    .join("\n");

runtime
    .call_function::<()>(Some(&module_handle), "clearLogBuffer", json_args!())
    .map_err(|err| (err.to_string(), None))?;

Conclusion

Rustyscript can do a lot more than what we've shared here - I recommend taking a look at the documentation if you've never used it before. For Superposition, Rustyscript's ability to run isolated JavaScript seamlessly from within Rust has unlocked richer correctness guarantees — we now support both validation and value-compute functions with full syntax checking and captured logs, without spawning a subprocess.

If you like the idea of Superposition, do take a look at our docs to learn more. Have questions? Join our Slack to interact with the team.