Configuration

This page documents all configuration options for the Replane clients.

Client Options

Both Replane and AsyncReplane accept the same configuration options:

from replane import Replane

replane = Replane(
    # Can be provided here or in connect()
    base_url="https://cloud.replane.dev",
    sdk_key="rp_...",

    # Optional
    context={"environment": "production"},
    defaults={"rate_limit": 100, "feature_enabled": False},
    required=["rate_limit", "feature_enabled"],
    request_timeout_ms=2000,
    initialization_timeout_ms=5000,
    retry_delay_ms=200,
    inactivity_timeout_ms=30000,
    debug=False,
)

Connection Options

base_url

• Type: str

• Required: Yes (in constructor or connect())

The base URL of your Replane server. Can be provided in the constructor or in connect().

# In constructor
replane = Replane(base_url="https://cloud.replane.dev", sdk_key="...")

# Or in connect()
replane = Replane(sdk_key="...")
replane.connect(base_url="https://cloud.replane.dev")

sdk_key

• Type: str

• Required: Yes (in constructor or connect())

Your SDK key from the Replane dashboard. Can be provided in the constructor or in connect().

# In constructor
replane = Replane(base_url="...", sdk_key="rp_abc123...")

# Or in connect()
replane = Replane(base_url="...")
replane.connect(sdk_key="rp_abc123...")

Optional Options

context

• Type: dict[str, str | int | float | bool | None]

• Default: {}

Default context applied to all config accesses. This is merged with any context passed via with_context().

# Set default context
replane = Replane(
    ...,
    context={
        "environment": "production",
        "region": "us-east",
    },
)

# This uses the default context
value = replane.configs["config_name"]

# This merges with default context using with_context()
user_client = replane.with_context({"user_id": "123"})
value = user_client.configs["config_name"]
# Effective context: {"environment": "production", "region": "us-east", "user_id": "123"}

defaults

• Type: dict[str, Any]

• Default: {}

Default values used when configs can’t be loaded from the server. This is useful for resilience - your application can still function with sensible defaults if the Replane server is unavailable.

replane = Replane(
    ...,
    defaults={
        "rate_limit": 100,
        "feature_enabled": False,
        "max-connections": 10,
    },
)

Defaults are used in two scenarios:

1. During initialization if a config isn’t returned by the server

2. If configs are accessed before initialization completes

required

• Type: list[str]

• Default: []

List of config names that must be present after initialization. If any required config is missing, initialization will fail with a ConfigNotFoundError.

replane = Replane(
    ...,
    required=["rate_limit", "feature_enabled"],
)
# Raises ConfigNotFoundError if either config is missing

This is useful for catching configuration errors early rather than at runtime.

request_timeout_ms

• Type: int

• Default: 2000 (2 seconds)

Timeout for individual HTTP requests to the Replane server.

replane = Replane(
    ...,
    request_timeout_ms=5000,  # 5 seconds
)

initialization_timeout_ms

• Type: int

• Default: 5000 (5 seconds)

Maximum time to wait for the client to initialize and receive configs from the server.

replane = Replane(
    ...,
    initialization_timeout_ms=10000,  # 10 seconds
)

If initialization times out, a TimeoutError is raised.

retry_delay_ms

• Type: int

• Default: 200 (0.2 seconds)

Initial delay between retry attempts when the connection fails. The delay increases exponentially with each retry (up to 30 seconds max).

replane = Replane(
    ...,
    retry_delay_ms=500,  # Start with 0.5 seconds
)

inactivity_timeout_ms

• Type: int

• Default: 30000 (30 seconds)

Maximum time without receiving any SSE events before the connection is considered stale and reconnected. The server sends periodic keepalive pings, so this timeout should be longer than the server’s ping interval.

replane = Replane(
    ...,
    inactivity_timeout_ms=60000,  # 60 seconds
)

debug

• Type: bool

• Default: False

Enable debug logging to see detailed information about all client activity. This is useful for troubleshooting connection issues, understanding when configs are loaded, and diagnosing override evaluation.

replane = Replane(
    ...,
    debug=True,  # Enable debug logging
)

When enabled, you’ll see logs for:

• Client initialization parameters

• SSE connection attempts and status

• Each config loaded from the server

• Config retrieval with context and evaluated value

• SSE events received

• Reconnection attempts

• Client close operations

Example output:

2024-01-15 10:30:00 [DEBUG] replane: Initializing Replane: base_url=https://cloud.replane.dev, ...
2024-01-15 10:30:00 [DEBUG] replane: connect() called, wait=True
2024-01-15 10:30:00 [DEBUG] replane: Connecting to SSE: host=cloud.replane.dev, port=443, https=True
2024-01-15 10:30:00 [DEBUG] replane: Response status: 200 OK
2024-01-15 10:30:00 [DEBUG] replane: SSE event received: type=init
2024-01-15 10:30:00 [DEBUG] replane: Loaded config: rate_limit (value=100, overrides=2)
2024-01-15 10:30:00 [DEBUG] replane: Initialization complete: 5 configs loaded

Manual Lifecycle Management

If you prefer not to use context managers, you can manage the client lifecycle manually:

Sync Client

replane = Replane(base_url="...", sdk_key="...")

# Connect and wait for initialization
replane.connect()  # Blocks until ready

try:
    value = replane.configs["config"]
finally:
    replane.close()

You can also connect without waiting:

replane.connect(wait=False)  # Returns immediately

# Do other initialization...

# Wait for configs when needed
replane.wait_for_init()

Async Client

replane = AsyncReplane(base_url="...", sdk_key="...")

await replane.connect()

try:
    value = replane.configs["config"]
finally:
    await replane.close()

Environment Variables

While the SDK doesn’t read environment variables directly, a common pattern is:

import os

replane = Replane(
    base_url=os.environ["REPLANE_URL"],
    sdk_key=os.environ["REPLANE_SDK_KEY"],
)