# Connections

For documentation on connecting to actors from clients, see the [Clients documentation](/actors/docs/clients).

## Parameters

When clients connect to an actor, they can pass connection parameters that are handled during the connection process. Use `params` for static values, or `getParams` when you need fresh connection data each time a connection opens.

For example:

Client:

```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface ConnParams {
  authToken: string;
}

interface ConnState {
  userId: string;
  role: string;
}

const gameRoom = actor({
  state: {},
  createConnState: (c, params: ConnParams): ConnState => {
    return { userId: "user-123", role: "player" };
  },
  actions: {}
});

const registry = setup({ use: { gameRoom } });
const client = createClient<typeof registry>("http://localhost:6420");

async function getAuthToken(): Promise<string> {
  return "supersekure";
}

const gameRoomHandle = client.gameRoom.getOrCreate(["room-123"], {
  getParams: async () => ({
    authToken: await getAuthToken(),
  })
});
```

Actor:

```ts
import { actor } from "rivetkit";

interface ConnParams {
  authToken: string;
}

interface ConnState {
  userId: string;
  role: string;
}

// Example validation functions
function validateToken(token: string): boolean {
  return token.length > 0;
}

function getUserIdFromToken(token: string): string {
  return "user-" + token.slice(0, 8);
}

const gameRoom = actor({
  state: {},

  // Handle connection setup
  createConnState: (c, params: ConnParams): ConnState => {
    // Validate authentication token
    const authToken = params.authToken;

    if (!authToken || !validateToken(authToken)) {
      throw new Error("Invalid auth token");
    }

    // Create connection state
    return { userId: getUserIdFromToken(authToken), role: "player" };
  },

  actions: {}
});
```

## Connection State

There are two ways to define an actor's connection state:

	
### connState

		Define connection state as a constant value:

		
examples/docs/actors-connections/conn-state-const.ts:

```ts
import { actor } from "rivetkit";

const chatRoom = actor({
  state: { messages: [] },

  // Define default connection state as a constant
  connState: {
    role: "guest",
    joinedAt: 0
  },

  onConnect: (c) => {
    // Update join timestamp when a client connects
    c.conn.state.joinedAt = Date.now();
  },

  actions: {
    // ...
  }
});
```

		This value will be cloned for every new connection using `structuredClone`.
	

	
### createConnState

		Create connection state dynamically with a function called for each connection:

		
examples/docs/actors-connections/conn-state-dynamic.ts:

```ts
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
  role: string;
  joinedAt: number;
}

interface Message {
  username: string;
  message: string;
}

function generateUserId(): string {
  return "user-" + Math.random().toString(36).slice(2, 11);
}

const chatRoom = actor({
  state: { messages: [] as Message[] },

  // Create connection state dynamically
  createConnState: (c): ConnState => {
    // Return the connection state
    return {
      userId: generateUserId(),
      role: "guest",
      joinedAt: Date.now()
    };
  },

  actions: {
    sendMessage: (c, message: string) => {
      const username = c.conn.state.userId;
      c.state.messages.push({ username, message });
      c.broadcast("newMessage", { username, message });
    }
  }
});
```

	

## Connection Lifecycle

Each client connection goes through a series of lifecycle hooks that allow you to validate, initialize, and clean up connection-specific resources.

**On Connect** (per client)

- `onBeforeConnect`
- `createConnState`
- `onConnect`

Pending connections are not visible in `c.conns` while `onBeforeConnect` or `createConnState` is running. RivetKit adds the connection to `c.conns` after those hooks succeed and before `onConnect` runs.

**On Disconnect** (per client)

- `onDisconnect`

### `createConnState` and `connState`

There are two ways to define the initial state for connections:
1. `connState`: Define a constant object that will be used as the initial state for all connections
2. `createConnState`: A function that dynamically creates initial connection state based on connection parameters. Can be async.

Connections are not visible in `c.conns` until `createConnState` completes successfully.

### `onBeforeConnect`

The `onBeforeConnect` hook is called whenever a new client connects to the actor. Can be async. Clients can pass parameters when connecting, accessible via `params`. This hook is used for connection validation and can throw errors to reject connections.

The `onBeforeConnect` hook does NOT return connection state - it's used solely for validation.

Connections are not visible in `c.conns` while `onBeforeConnect` is running.

examples/docs/actors-connections/on-before-connect.ts:

```ts
import { actor } from "rivetkit";

interface Message {
  text: string;
  author: string;
}

interface ConnParams {
  authToken?: string;
  userId?: string;
  role?: string;
}

interface ConnState {
  userId: string;
  role: string;
  joinTime: number;
}

function validateToken(token: string): boolean {
  return token.length > 0;
}

const chatRoom = actor({
  state: { messages: [] as Message[] },

  // Dynamically create connection state
  createConnState: (c, params: ConnParams): ConnState => {
    return {
      userId: params.userId || "anonymous",
      role: params.role || "guest",
      joinTime: Date.now()
    };
  },

  // Validate connections before accepting them
  onBeforeConnect: (c, params: ConnParams) => {
    // Validate authentication
    const authToken = params.authToken;
    if (!authToken || !validateToken(authToken)) {
      throw new Error("Invalid authentication");
    }

    // Authentication is valid, connection will proceed
    // The actual connection state will come from createConnState
  },

  actions: {}
});
```

Connections cannot interact with the actor until this method completes successfully. Throwing an error will abort the connection. This can be used for authentication, see [Authentication](/actors/docs/authentication) for details.

### `onConnect`

Executed after the client has successfully connected. Can be async. Receives the connection object as a second parameter.

By the time `onConnect` runs, the connection is visible in `c.conns`.

examples/docs/actors-connections/on-connect.ts:

```ts
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
}

interface UserStatus {
  online: boolean;
  lastSeen: number;
}

const chatRoom = actor({
  state: { users: {} as Record<string, UserStatus>, messages: [] as string[] },

  createConnState: (): ConnState => ({
    userId: "user-" + Math.random().toString(36).slice(2, 11)
  }),

  onConnect: (c, conn) => {
    // Add user to the room's user list using connection state
    const userId = conn.state.userId;
    c.state.users[userId] = {
      online: true,
      lastSeen: Date.now()
    };

    // Broadcast that a user joined
    c.broadcast("userJoined", { userId, timestamp: Date.now() });

    console.log(`User ${userId} connected`);
  },

  actions: {}
});
```

Messages will not be processed for this actor until this hook succeeds. Errors thrown from this hook will cause the client to disconnect.

### `onDisconnect`

Called when a client disconnects from the actor. Can be async. Receives the connection object as a second parameter. Use this to clean up any connection-specific resources.

examples/docs/actors-connections/on-disconnect.ts:

```ts
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
}

interface UserStatus {
  online: boolean;
  lastSeen: number;
}

const chatRoom = actor({
  state: { users: {} as Record<string, UserStatus>, messages: [] as string[] },

  createConnState: (): ConnState => ({
    userId: "user-" + Math.random().toString(36).slice(2, 11)
  }),

  onDisconnect: (c, conn) => {
    // Update user status when they disconnect
    const userId = conn.state.userId;
    if (c.state.users[userId]) {
      c.state.users[userId].online = false;
      c.state.users[userId].lastSeen = Date.now();
    }

    // Broadcast that a user left
    c.broadcast("userLeft", { userId, timestamp: Date.now() });

    console.log(`User ${userId} disconnected`);
  },

  actions: {}
});
```

## Connection List

All active connections can be accessed through the context object's `conns` property. This is a `Map<string, Conn>` of all current connections, keyed by connection ID.

This is frequently used with `conn.send(name, event)` to send messages directly to clients. To send an event to all connections at once, use `c.broadcast()` instead. See [Events](/actors/docs/events) for more details on broadcasting.

For example:

examples/docs/actors-connections/connection-list.ts:

```ts
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
}

const chatRoom = actor({
  state: { users: {} as Record<string, { online: boolean }> },

  createConnState: (): ConnState => ({
    userId: "user-" + Math.random().toString(36).slice(2, 11)
  }),

  actions: {
    sendDirectMessage: (c, recipientId: string, message: string) => {
      // Find the recipient's connection by iterating over the Map
      let recipientConn = null;
      for (const conn of c.conns.values()) {
        if (conn.state.userId === recipientId) {
          recipientConn = conn;
          break;
        }
      }

      if (recipientConn) {
        // Send a private message to just that client
        recipientConn.send("directMessage", {
          from: c.conn.state.userId,
          message: message
        });
      }
    }
  }
});
```

> **NOTE:** `conn.send()` has no effect on [low-level WebSocket connections](/actors/docs/websocket-handler). For low-level WebSockets, use the WebSocket API directly (e.g., `websocket.send()`).

## Disconnecting clients

Connections can be disconnected from within an action:

examples/docs/actors-connections/disconnect-clients.ts:

```ts
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
}

const secureRoom = actor({
  state: {},

  createConnState: (): ConnState => ({
    userId: "user-" + Math.random().toString(36).slice(2, 11)
  }),

  actions: {
    kickUser: (c, targetUserId: string, reason?: string) => {
      // Find the connection to kick by iterating over the Map
      for (const conn of c.conns.values()) {
        if (conn.state.userId === targetUserId) {
          // Disconnect with a reason
          conn.disconnect(reason || "Kicked by admin");
          break;
        }
      }
    }
  }
});
```

If you need to wait for the disconnection to complete, you can use `await`:

examples/docs/actors-connections/disconnect-await.ts:

```ts
import { actor } from "rivetkit";

const myActor = actor({
  state: {},
  actions: {
    disconnect: async (c) => {
      await c.conn.disconnect("Too many requests");
    }
  }
});
```

This ensures the underlying network connections close cleanly before continuing.