FFI Interface For Config Resolution

[sauraww]

Key Interface Components

1. Client LifeCycle Management

// Create a client and return its handle
#[no_mangle]
pub extern "C" fn core_create_client(
    tenant: *const c_char,
    polling_interval_seconds: u64,
    hostname: *const c_char,
) -> ClientHandle { /* ... */ }

// Free a client when done
#[no_mangle]
pub extern "C" fn core_free_client(client_handle: ClientHandle) -> bool { /* ... */ }

2. Configuration Resolution

// Get resolved config using client handle
#[no_mangle]
pub extern "C" fn core_get_resolved_config_with_client(
    client_handle: ClientHandle,
    query_data_json: *const c_char,
    filter_keys_json: *const c_char,
    merge_strategy_str: *const c_char,
) -> *mut c_char { /* ... */ }

3. Caching Control

// Configure global cache
#[no_mangle]
pub extern "C" fn core_configure_cache(
    max_capacity_mb: u64,
    ttl_seconds: u64,
    tti_seconds: u64,
) -> bool { /* ... */ }

How Client Handles Work
The ClientHandle system is the backbone of our FFI design:

1. Clients are stored in a global map:

pub static CLIENT_MAP: Lazy<RwLock<HashMap<ClientHandle, Arc<Client>>>> =
    Lazy::new(|| RwLock::new(HashMap::new()));

2. Each client gets a unique ID from an incrementing counter:

pub static CLIENT_HANDLE_COUNTER: Lazy<RwLock<ClientHandle>> =
    Lazy::new(|| RwLock::new(1));

3. FFI functions take a ClientHandle parameter to identify which client to operate on.

Async/Sync Bridging
it uses thread-local Tokio runtimes to make async Rust code accessible through synchronous FFI functions

thread_local! {
    static RUNTIME: RefCell<Option<Runtime>> = RefCell::new(None);
}

fn get_runtime() -> Result<&'static Runtime, String> {
    RUNTIME.with(|rt| {
        if rt.borrow().is_none() {
            // Create new runtime for this thread
            match Runtime::new() {
                Ok(new_rt) => {
                    *rt.borrow_mut() = Some(new_rt);
                }
                Err(e) => {
                    return Err(format!("Failed to create Tokio runtime: {}", e));
                }
            }
        }

        // Return reference to runtime
        Ok(unsafe {
            std::mem::transmute::<&Runtime, &'static Runtime>(
                rt.borrow().as_ref().unwrap(),
            )
        })
    })
}

Example Usage Flow:

// 1. Create a client for a specific tenant
const clientHandle = lib.core_create_client("tenant1", 30, "http://localhost:8080");
if (clientHandle === -1) {
    // Check for error
    const errorLength = lib.core_last_error_length();
    if (errorLength > 0) {
        const errorPtr = lib.core_last_error_message();
        const errorMessage = koffi.decode(errorPtr, 'string');
        lib.core_free_string(errorPtr);
        console.error("Error creating client:", errorMessage);
    }
    return;
}

try {
    // 2. Start polling for configuration updates
    const pollingResult = lib.core_start_polling(clientHandle);
    if (!pollingResult) {
        // Handle error...
    }
    
    // 3. Resolve configuration based on query parameters
    const queryData = JSON.stringify({ "os": "android", "clientId": "meesho" });
    const filterKeys = JSON.stringify(["feature1", "feature2"]); 
    const mergeStrategy = "MERGE";
    
    const resultPtr = lib.core_get_resolved_config_with_client(
        clientHandle,
        queryData,
        filterKeys,
        mergeStrategy
    );
    
    if (!resultPtr) {
        // Handle error...
    }
    
    // 4. Parse result
    const resultStr = koffi.decode(resultPtr, 'string');
    lib.core_free_string(resultPtr);
    const config = JSON.parse(resultStr);
    
    console.log("Resolved config:", config);
} finally {
    // 5. Free resources when done
    lib.core_free_client(clientHandle);
}

[sauraww]

import { CACClient, CACClientOptions } from './cac-client';
import { ExperimentationClient, ExperimentationClientOptions } from './experimentation-client';
import { NativeResolver } from './native';

export interface SuperpositionConfig {
  endpoint: string;
  token?: {
    token: string;
  };
  org_id?: string;
  workspace_id?: string;
}

export class SuperpositionClient {
  private config: SuperpositionConfig;
  private resolver: NativeResolver;
  
  constructor(config: SuperpositionConfig) {
    this.config = config;
    this.resolver = new NativeResolver();
  }
  
  getCACClient(options: CACClientOptions = {}) {
    return new CACClient(this.config, this.resolver, options);
  }
  
  getExperimentationClient(options: ExperimentationClientOptions = {}) {
    return new ExperimentationClient(this.config, this.resolver, options);
  }
}

const config: any = { 
  endpoint: ENV.baseUrl, 
  token: { 
    token: "some-token", 
  },
};

export const superpositionClient = new SuperpositionClient(config);

const cacClient = superpositionClient.getCACClient({ 
  refreshStrategy: { 
    type: 'polling', 
    intervalMs: 30000 
  } 
});

This is cac-client.ts

import { SuperpositionConfig } from './types';
import { NativeResolver } from './native';

export interface CACClientOptions {
  refresh?: {
    strategy?: 'polling' | 'manual';
    interval?: number;
  };
  fallback?: {
    strategy?: 'use-last-known' | 'use-defaults' | 'fail';
    defaults?: any;
  };
  cache?: {
    ttl?: number;
    tti?: number;
  };
}

export interface EvalOptions {
  refresh?: boolean;
  filterKeys?: string[];
  mergeStrategy?: 'merge' | 'replace';
  timeout?: number;
}

export class CACClient {
  private config: SuperpositionConfig;
  private resolver: NativeResolver;
  private options: CACClientOptions;
  private cachedData: any = null;
  private lastFetchTime: number = 0;
  private refreshInterval: NodeJS.Timeout | null = null;
  private refreshPromise: Promise<any> | null = null;
  
  constructor(
    config: SuperpositionConfig,
    resolver: NativeResolver,
    options: CACClientOptions = {}
  ) {
    this.config = config;
    this.resolver = resolver;
    this.options = options;
    
    // Initialize with defaults if provided
    if (options.fallback?.defaults) {
      this.cachedData = options.fallback.defaults;
      this.lastFetchTime = Date.now();
    }
    
    // Setup automatic refresh if specified
    if (options.refresh?.strategy === 'polling' && options.refresh.interval) {
      this.setupRefresh(options.refresh.interval);
    }
  }
  

  async eval(context: Record<string, any>, options: EvalOptions = {}): Promise<any> {
    try {
      // Force refresh if requested
      if (options.refresh) {
        await this.refresh();
      }
      
      // Get configuration data (from cache or fresh)
      const configData = await this.getConfigData();
      
      // Resolve configuration using the native resolver
      return this.resolver.resolveConfig(
        configData.defaultConfigs,
        configData.contexts,
        configData.overrides,
        context,
        options.mergeStrategy || 'merge',
        options.filterKeys
      );
    } catch (error) {
      // Handle errors based on fallback strategy
      const fallbackStrategy = this.options.fallback?.strategy || 'fail';
      
      if (fallbackStrategy === 'use-last-known' && this.cachedData) {
        return this.resolver.resolveConfig(
          this.cachedData.defaultConfigs,
          this.cachedData.contexts,
          this.cachedData.overrides,
          context,
          options.mergeStrategy || 'merge',
          options.filterKeys
        );
      }
      
      if (fallbackStrategy === 'use-defaults' && this.options.fallback?.defaults) {
        return this.resolver.resolveConfig(
          this.options.fallback.defaults.defaultConfigs,
          this.options.fallback.defaults.contexts,
          this.options.fallback.defaults.overrides,
          context,
          options.mergeStrategy || 'merge',
          options.filterKeys
        );
      }
      
      // If no fallback or strategy is 'fail', rethrow the error
      throw error;
    }
  }
  
  async refresh(options: { timeout?: number } = {}): Promise<void> {
    try {
      // If already refreshing, return that promise
      if (this.refreshPromise) {
        return this.refreshPromise;
      }
      
      // Create and store refresh promise
      this.refreshPromise = this.fetchConfigData(options.timeout);
      
      // Wait for completion
      await this.refreshPromise;
    } finally {
      // Clear refresh promise
      this.refreshPromise = null;
    }
  }
  
  setupRefresh(intervalMs: number = 30000): void {
    // Clear existing interval if any
    this.stopRefresh();
    
    // Set up new interval
    this.refreshInterval = setInterval(async () => {
      try {
        await this.refresh();
      } catch (error) {
        console.error('Failed to refresh configuration:', error);
      }
    }, intervalMs);
  }
  

  stopRefresh(): void {
    if (this.refreshInterval) {
      clearInterval(this.refreshInterval);
      this.refreshInterval = null;
    }
  }
  
  /**
   * Get configuration data (from cache or fetch)
   */
  private async getConfigData(): Promise<any> {
    const cacheTtl = this.options.cache?.ttl || 60000; // Default 1 minute
    const now = Date.now();
    
    // Use cached data if available and not expired
    if (this.cachedData && now - this.lastFetchTime < cacheTtl) {
      return this.cachedData;
    }
    
    // Fetch fresh data
    return this.fetchConfigData();
  }
  
  /**
   * Fetch configuration data from the server
   */
  private async fetchConfigData(timeoutMs?: number): Promise<any> {
    // Build request headers
    const headers: Record<string, string> = {
      'Content-Type': 'application/json'
    };
    
    if (this.config.token?.token) {
      headers['Authorization'] = `Bearer ${this.config.token.token}`;
    }
    
    if (this.config.org_id) {
      headers['X-Organization-ID'] = this.config.org_id;
    }
    
    if (this.config.workspace_id) {
      headers['X-Workspace-ID'] = this.config.workspace_id;
    }
    
    // Create fetch request
    const fetchPromise = fetch(`${this.config.endpoint}/config`, {
      headers,
      signal: timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined
    });
    
    // Execute request
    const response = await fetchPromise;
    
    if (!response.ok) {
      throw new Error(`Failed to fetch configuration: ${response.status} ${response.statusText}`);
    }
    
    // Parse and store data
    const data = await response.json();
    this.cachedData = data;
    this.lastFetchTime = Date.now();
    
    return data;
  }
 
}