# Sessions

The Sessions service tracks client connections to zenserver. Each session
represents a logical connection from a client application — an Unreal Editor
instance, a build agent, a CLI tool, or any other process interacting with the
server.

## Concepts

### Session

A session is identified by a unique OID and carries:

- **AppName** — the name of the connecting application (e.g. `UnrealEditor`,
  `zen`)
- **Mode** — the operational mode of the client
- **JobId** — an optional job identifier for build farm scenarios
- **Metadata** — arbitrary key-value data attached by the client
- **Timestamps** — creation, last update, and end times

### Session Log

Each session has an associated log stream that can receive entries from the
client or from zenserver itself. The server's own session captures internal log
output, making it visible in the web dashboard.

Log entries contain a timestamp, severity level (`debug`, `info`, `warn`,
`error`), a message string, and optional structured data fields.

Logs are kept in memory with a maximum of 10,000 entries per session. When the
limit is exceeded, the oldest entries are evicted.

## API

**Base URI:** `/sessions/`

### Listing Sessions

```
GET /sessions/                  # Active sessions (default)
GET /sessions/?status=ended     # Ended sessions
GET /sessions/?status=all       # All sessions
```

### Managing Sessions

```
POST   /sessions/{id}           # Create or update a session
PUT    /sessions/{id}           # Update session metadata
DELETE /sessions/{id}           # End and remove a session
GET    /sessions/{id}           # Get session details
```

When creating a session, the request body should contain:

- `appname` — application name
- `mode` — operational mode
- `jobid` — optional job identifier
- `metadata` — optional key-value metadata

### Session Logs

```
GET  /sessions/{id}/log             # Retrieve log entries
POST /sessions/{id}/log             # Append log entries
```

**Retrieving logs** supports two modes:

- **Cursor-based** (recommended): pass `?cursor=N` where N is the cursor value
  from the previous response. Returns only entries appended since that cursor.
- **Offset/limit**: pass `?offset=N&limit=M` for traditional pagination.

**Appending logs** accepts:

- **Plain text** — each line becomes a separate log entry
- **JSON** — a single log object or `{"entries": [...]}` array, each with
  `level`, `message`, and optional `data` fields

### Live Updates

```
GET /sessions/ws                # WebSocket connection
```

The WebSocket endpoint pushes the full session list to connected clients
periodically. This powers the real-time session table in the web dashboard.

## Web Dashboard

The Sessions page in the dashboard provides:

- A table of active, ended, or all sessions with sorting and pagination
- Session detail panel showing metadata and properties
- Live log viewer with follow mode, newest-first ordering, and text filtering
- The server's own session is selected by default on page load