Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion docs/content/development/connector.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ graph LR

**Initial Connection**:
1. Target app starts → SDK initializes `RhesisClient` with `project_id` and `environment`
2. SDK establishes WebSocket connection to backend (`/ws/connector`)
2. SDK establishes WebSocket connection to backend (`/connector/ws`)
3. SDK sends registration message with function metadata
4. Backend stores connection and creates endpoint records

Expand All @@ -59,6 +59,19 @@ graph LR
6. Backend publishes result to Redis (`ws:rpc:response:{test_run_id}`)
7. Worker subscribes and receives result

### Connector hardening controls (v0.6.8+)

The SDK connector WebSocket endpoint (`/connector/ws`) applies runtime safeguards configurable
with backend environment variables:

| Variable | Default | Behavior |
|---|---|---|
| `WS_MAX_MESSAGE_SIZE` | `1048576` (1 MiB) | Rejects oversized SDK connector WebSocket messages |
| `WS_IDLE_TIMEOUT` | `300` seconds | Closes inactive SDK connector WebSocket sessions |
| `WS_RATE_LIMIT` | `50` messages/second | Applies per-connection sliding-window rate limiting |

These limits apply specifically to SDK connector traffic, not to all platform WebSocket usage.

## Backend Components

### Connection Manager
Expand Down Expand Up @@ -172,6 +185,9 @@ if await rpc_client.is_connected(project_id, environment):
}`}
</CodeBlock>

`project_id` and `environment` are optional in register messages for metrics-only sessions.
When they are omitted, the backend skips endpoint synchronization and still syncs registered SDK metrics.

## Endpoint Synchronization

When SDK registers functions, backend automatically:
Expand Down
3 changes: 3 additions & 0 deletions docs/content/development/environment-variables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ Create a `.env` file in `apps/backend/` with the following variables:
['`FRONTEND_URL`', 'Default: `http://localhost:3000`', 'Frontend application URL for CORS and redirects'],
['`RHESIS_BASE_URL`', '**Required** (production)', 'Backend API base URL. Defaults to `https://api.rhesis.ai`. **Must be explicitly set for production deployments** — OAuth callback URLs are derived from this value, so a missing or incorrect value will break authentication flows'],
['`BACKEND_URL`', 'Default: `http://backend:8080`', 'Internal backend URL for service-to-service communication'],
['`WS_MAX_MESSAGE_SIZE`', 'Default: `1048576` (1 MiB)', 'Maximum payload size in bytes for SDK connector WebSocket messages (`/connector/ws`)'],
['`WS_IDLE_TIMEOUT`', 'Default: `300`', 'Idle timeout in seconds for SDK connector WebSocket connections (`/connector/ws`)'],
['`WS_RATE_LIMIT`', 'Default: `50`', 'Maximum SDK connector WebSocket messages per second (sliding window, per connection)'],
['`RHESIS_BASE_PATH`', 'Optional', 'Base filesystem path to Rhesis installation directory'],
['`QUICK_START`', 'Default: `false`', 'Enable Quick Start mode for local development. **Never enable in production**'],
['`DEMO_USER_EMAIL`', 'Optional', 'Email address for demo user account'],
Expand Down
27 changes: 27 additions & 0 deletions docs/content/sdk/connector/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,33 @@ if __name__ == "__main__":
Any unsupported parameter names cause registration-time errors.
</Callout>

### Metrics-only connector mode (optional `project_id`)

If your script only registers SDK metrics with `@metric`, `project_id` is optional.
In this mode, the connector still establishes a WebSocket session and registers metrics for backend-side evaluation.

<CodeBlock filename="metrics_only.py" language="python">
{`from rhesis.sdk import RhesisClient, metric

client = RhesisClient(
api_key="your-api-key",
environment="development",
)

@metric(name="contains_policy_reference", score_type="binary")
def contains_policy_reference(input: str, output: str, context: list[str] | None = None) -> dict:
has_reference = bool(context) and any(ref in output for ref in context)
return {"score": 1.0 if has_reference else 0.0}

if __name__ == "__main__":
client.connect()`}
</CodeBlock>

<Callout type="info">
`@endpoint` registrations still require `project_id`. The optional `project_id` behavior applies to
metrics-only connector usage.
</Callout>

### See It in Action

Watch this video to see how the Rhesis SDK connector integrates an LLM application in under a minute using a single decorator:
Expand Down
Loading