77 lines
4.1 KiB
Markdown
77 lines
4.1 KiB
Markdown
# `server`: The Circles WebSocket Server
|
|
|
|
The `server` crate provides a secure, high-performance WebSocket server built with `Actix`. It is the core backend component of the `circles` ecosystem, responsible for handling client connections, processing JSON-RPC requests, and executing Rhai scripts in a secure manner.
|
|
|
|
## Features
|
|
|
|
- **`Actix` Framework**: Built on `Actix`, a powerful and efficient actor-based web framework.
|
|
- **WebSocket Management**: Uses `actix-web-actors` to manage each client connection in its own isolated actor (`CircleWs`), ensuring robust and concurrent session handling.
|
|
- **JSON-RPC 2.0 API**: Implements a JSON-RPC 2.0 API for all client-server communication. The API is formally defined in the root [openrpc.json](../../openrpc.json) file.
|
|
- **Secure Authentication**: Features a built-in `secp256k1` signature-based authentication system to protect sensitive endpoints.
|
|
- **Stateful Session Management**: The `CircleWs` actor maintains the authentication state for each client, granting or denying access to protected methods like `play`.
|
|
- **Webhook Integration**: Supports HTTP webhook endpoints for external services (Stripe, iDenfy) with signature verification and script execution capabilities.
|
|
|
|
## Core Components
|
|
|
|
### `spawn_circle_server`
|
|
|
|
This is the main entry point function for the server. It configures and starts the `Actix` HTTP server and sets up the WebSocket route with path-based routing (`/{circle_pk}`).
|
|
|
|
### `CircleWs` Actor
|
|
|
|
This `Actix` actor is the heart of the server's session management. A new instance of `CircleWs` is created for each client that connects. Its responsibilities include:
|
|
- Handling the WebSocket connection lifecycle.
|
|
- Parsing incoming JSON-RPC messages.
|
|
- Managing the authentication state of the session (i.e., whether the client is authenticated or not).
|
|
- Dispatching requests to the appropriate handlers (`fetch_nonce`, `authenticate`, and `play`).
|
|
|
|
## Authentication
|
|
|
|
The server provides a robust authentication mechanism to ensure that only authorized clients can execute scripts. The entire flow is handled over the WebSocket connection using two dedicated JSON-RPC methods:
|
|
|
|
1. **`fetch_nonce`**: The client requests a unique, single-use nonce (a challenge) from the server.
|
|
2. **`authenticate`**: The client sends back the nonce signed with its private key. The `CircleWs` actor verifies the signature to confirm the client's identity.
|
|
|
|
For a more detailed breakdown of the authentication architecture, please see the [ARCHITECTURE.md](docs/ARCHITECTURE.md) file.
|
|
|
|
## Webhook Integration
|
|
|
|
The server also provides HTTP webhook endpoints for external services alongside the WebSocket functionality:
|
|
|
|
- **Stripe Webhooks**: `POST /webhooks/stripe/{circle_pk}` - Handles Stripe payment events
|
|
- **iDenfy Webhooks**: `POST /webhooks/idenfy/{circle_pk}` - Handles iDenfy KYC verification events
|
|
|
|
### Webhook Features
|
|
|
|
- **Signature Verification**: All webhooks use HMAC signature verification for security
|
|
- **Script Execution**: Webhook events trigger Rhai script execution via the same Redis-based system
|
|
- **Type Safety**: Webhook payload types are defined in the `heromodels` library for reusability
|
|
- **Modular Architecture**: Separate handlers for each webhook provider with common utilities
|
|
|
|
For detailed webhook architecture and configuration, see [WEBHOOK_ARCHITECTURE.md](WEBHOOK_ARCHITECTURE.md).
|
|
|
|
## How to Run
|
|
|
|
### As a Library
|
|
|
|
The `server` is designed to be used as a library by the `launcher`, which is responsible for spawning a single multi-circle server instance that can handle multiple circles via path-based routing.
|
|
|
|
To run the server via the launcher with circle public keys:
|
|
```bash
|
|
cargo run --package launcher -- -k <circle_public_key1> -k <circle_public_key2> [options]
|
|
```
|
|
|
|
The launcher will start a single `server` instance that can handle multiple circles through path-based WebSocket connections at `/{circle_pk}`.
|
|
|
|
### Standalone Binary
|
|
|
|
A standalone binary is also available for development and testing purposes. See [`cmd/README.md`](cmd/README.md) for detailed usage instructions.
|
|
|
|
```bash
|
|
# Basic standalone server
|
|
cargo run
|
|
|
|
# With authentication and TLS
|
|
cargo run -- --auth --tls --cert cert.pem --key key.pem
|
|
```
|