Server API

The ServerCoordinator is the core of the TopGun backend. It manages client connections, synchronization logic, clustering, and security enforcement.

Configuration

interface ServerCoordinatorConfig

Parameters

  • port
    number. Port to listen on for WebSocket connections.
  • storage?
    IServerStorage. Backend storage adapter. Available adapters: PostgresAdapter (production), MemoryServerAdapter (testing). If omitted, runs in-memory.
  • securityPolicies?
    PermissionPolicy[]. List of RBAC policies. See RBAC Guide.
  • clusterPort?
    number. Port for inter-node communication.
  • peers?
    string[]. List of initial peer addresses for clustering (e.g., ['node2:8000']).
  • tls?
    TLSConfig. TLS configuration for client-facing connections (HTTPS/WSS). See TLS Configuration below.
  • clusterTls?
    ClusterTLSConfig. TLS configuration for inter-node cluster communication. Supports mTLS.

TLS Configuration

Enable TLS/SSL encryption for secure client connections (WSS) and cluster communication.
interface TLSConfig

Parameters

  • enabled
    boolean. Enable TLS for client-facing server (HTTPS + WSS). Default: false
  • certPath
    string. Path to the certificate file (PEM format). Supports chain certificates.
  • keyPath
    string. Path to the private key file (PEM format).
  • caCertPath?
    string. Path to CA certificate for client certificate verification. Required for mTLS.
  • minVersion?
    'TLSv1.2' | 'TLSv1.3'. Minimum TLS version. Default: 'TLSv1.2'
  • ciphers?
    string. List of allowed cipher suites. Uses Node.js defaults if not specified.
  • passphrase?
    string. Passphrase for encrypted private key.
interface ClusterTLSConfig extends TLSConfig

Parameters

  • requireClientCert?
    boolean. Require client certificate for mTLS (mutual TLS). Default: false
  • rejectUnauthorized?
    boolean. Verify peer certificates. Can be disabled for self-signed certs in development. Default: true

Production Warning

When running in production without TLS enabled, the server will log a warning. Always enable TLS in production environments to protect client data in transit.

Methods

constructor(config)

Creates a new server instance but does not start listening immediately.

ready()

Returns a Promise that resolves when the server is fully started and bound to the port.
const server = new ServerCoordinator(config);
await server.ready();
console.log(`Server running on port ${server.port}`);

shutdown()

Gracefully shuts down the server, closing all client connections, stopping the cluster, and closing storage.
Previous

Data Structures API

Next

Adapter API