Quickstart

pip install "varianz==0.2.3" "varianz-pytest==0.2.3" \
  --extra-index-url https://pkgs.varianz.io/python/simple/

echo '@varianz:registry=https://pkgs.varianz.io/npm/' >> .npmrc
npm install --save @varianz/node@0.2.3
npm install --save-dev @varianz/vitest@0.2.3

go get go.varianz.io/sdk@v0.2.3

// settings.gradle.kts
pluginManagement {
    repositories {
        maven { url = uri("https://pkgs.varianz.io/maven") }
        gradlePluginPortal()
    }
}

// build.gradle.kts — Gradle 9.0+ on JDK 24+
plugins {
    id("java")
    id("io.varianz.sdk") version "0.2.3"
}
repositories {
    mavenCentral()
    maven { url = uri("https://pkgs.varianz.io/maven") }
}
varianz { sdkVersion.set("0.2.3") }

// build.gradle.kts — Kotlin 2.3+, KSP applied before the Varianz plugin
plugins {
    kotlin("jvm") version "2.3.21"
    id("com.google.devtools.ksp") version "2.3.11"
    id("io.varianz.sdk.kotlin") version "0.2.3"
}
repositories {
    mavenCentral()
    maven { url = uri("https://pkgs.varianz.io/maven") }
}
dependencies {
    ksp("com.github.javaparser:javaparser-core:3.27.0")
}
configure<io.varianz.gradle.kotlin.VarianzKotlinExtension> {
    sdkVersion.set("0.2.3")
}

# pricing.py
from varianz import Varianz

vz = Varianz("http://localhost:50051")

@vz.vpoint(name="pricing/calculate")
def calculate_price(amount: float, discount: float) -> float:
    return amount * (1 - discount)

vz.register(calculate_price)

// pricing.ts
import { createVPoints, initCoordinator } from '@varianz/node';

initCoordinator({
  endpoint: 'http://localhost:50051',
  applicationName: 'pricing-service',
});

export const { instrumented } = createVPoints('pricing', {
  calculate(amount: number, discount: number): number {
    return amount * (1 - discount);
  },
});

// Call through `instrumented` so stages can intercept:
instrumented.calculate(100, 0.1);

// pricing.go
package pricing

import (
    "context"
    "log"

    "go.varianz.io/sdk/varianz"
)

var vz = varianz.New(varianz.WithEndpoint("http://localhost:50051"))

type PricingRequest struct {
    Amount   float64
    Discount float64
}

var CalculatePrice = varianz.VPoint(vz, "pricing/calculate",
    func(ctx context.Context, req PricingRequest) (float64, error) {
        return req.Amount * (1 - req.Discount), nil
    },
)

func main() {
    if err := vz.Init(); err != nil {
        log.Fatal(err)
    }
    defer vz.Close()
    // CalculatePrice is the instrumented function — call it normally.
}

import io.varianz.annotations.vpoint.VPoint;
import io.varianz.binding.CoordinatorBinding;

public class PricingService {
    @VPoint(name = "pricing/calculate")
    public double calculatePrice(double amount, double discount) {
        return amount * (1 - discount);
    }
}

// At startup, before serving traffic:
CoordinatorBinding.init("http://localhost:50051");
PricingService service = new PricingService();
PricingServiceVPoints.bind(service);  // generated by the annotation processor

import io.varianz.annotations.vpoint.VPoint
import io.varianz.binding.CoordinatorBinding

class PricingService {
    @VPoint(name = "pricing/calculate")   // named arguments required in Kotlin
    fun calculatePrice(amount: Double, discount: Double): Double =
        amount * (1 - discount)
}

// At startup:
CoordinatorBinding.init("http://localhost:50051")
PricingServiceVPoints.bind(PricingService())

# test_pricing.py — the `varianz` fixture comes from varianz-pytest
from varianz import cel
from pricing import calculate_price  # registers the VPoint and connects the subscriber

def test_price_override(varianz):
    varianz.insert(cel("pricing/calculate", "42.0"))
    varianz.await_sync_or_fail(timeout_ms=5000)

    # The fixture has already activated the session for this test, so an
    # in-process call picks up the override directly. (Calls over HTTP/gRPC
    # carry the session in the x-varianz-id header instead.)
    assert calculate_price(100.0, 0.1) == 42.0

// pricing.test.ts
import { expect } from 'vitest';
import { varianzVitest, cel } from '@varianz/vitest';
import { instrumented } from './pricing';  // registers the VPoints and connects

// Same applicationName as pricing.ts: importing it already initialized the
// coordinator, and a second init with a different config throws.
const { test } = varianzVitest({
  endpoint: 'http://localhost:50051',
  applicationName: 'pricing-service',
});

test('price override', async ({ varianz }) => {
  await varianz.insert(cel('pricing/calculate', '42.0'));
  await varianz.awaitSyncOrFail(5_000);

  expect(instrumented.calculate(100, 0.1)).toBe(42);
});

// pricing_test.go — same package as step 3
import (
    "context"
    "log"
    "os"
    "testing"
    "time"

    "go.varianz.io/sdk/varianz"
    "go.varianz.io/sdk/varianztest"
)

// `go test` never runs main(), so the test binary needs its own Init().
func TestMain(m *testing.M) {
    if err := vz.Init(); err != nil {
        log.Fatal(err)
    }
    defer vz.Close()
    os.Exit(m.Run())
}

func TestPriceOverride(t *testing.T) {
    session := varianztest.NewSession(t, "http://localhost:50051")

    session.Insert(varianztest.Cel("pricing/calculate", "42.0"))
    session.AwaitSyncOrFail(5 * time.Second)

    // Call the service with the session ID in context:
    ctx := varianz.WithSession(context.Background(), session.SessionID())
    got, err := CalculatePrice(ctx, PricingRequest{Amount: 100, Discount: 0.1})
    if err != nil || got != 42.0 {
        t.Fatalf("got %v, err %v", got, err)
    }
}

@ExtendWith(VarianzExtension.class)
class PricingTest {
    @Test
    void priceOverride(VarianzSession session) {
        session.insert(cel("pricing/calculate", "42.0"));
        session.awaitSyncOrFail();

        // Trigger the service with session.sessionId() in the
        // x-varianz-id header / gRPC metadata, then assert.
    }
}