# Session Module

## Overview

The **Diarkis Session** module provides a lightweight, scoped communication context that supports integration with other Diarkis modules, including **Room**, **Group**, **Field**, and **DM**. It is designed for **temporary, stateful interactions** among a defined set of users, offering **controlled membership, event handling, and data sharing**.

**Core Capabilities:**

* **Session Membership Management:**\
  A Session supports a **maximum number of concurrent members**, defined at the time of creation. Users can be **invited dynamically**, but if the session’s capacity is full at the time of acceptance, the invitee will be **denied entry**. This allows for precise control over participant limits and session behavior.
* **Event Triggers:**\
  The Session module automatically emits **join, leave, and delete events**, allowing applications to respond to user state changes and session lifecycle transitions in real time.
* **Broadcast Messaging:**\
  Within an active session, **all members can exchange broadcast messages**, enabling real-time group coordination without requiring Room-based message routing.
* **Property Persistence (in-memory only):**\
  Sessions support **shared property storage**, allowing the system to **store and retrieve structured session-level metadata** (e.g., settings, context, or shared game state) for the duration of the session’s lifespan.

**Modular Compatibility:**

Sessions can operate in conjunction with other Diarkis modules, acting as a lightweight control layer or membership gateway. For example:

* Use with **Room** for scoped messaging and object synchronization.
* Use with **DM** for member-specific private messaging.
* Use with **Field** to track entity presence across servers.

For implementation specifics, configuration parameters, and method references, please consult the [**Diarkis Server API documentation**](https://docs.diarkis.io/docs/server/current/diarkis/session/index.html).

### Session Invitations

In the Diarkis Session module, the **session owner (creator)** holds the authority to invite users into the session by specifying their **unique user ID**. This invitation mechanism is designed for **controlled, authenticated entry** into temporary, scoped communication environments.

**Invitation Process:**

* **User-Specific Invitations:**\
  Invitations are issued on a **per-user basis** and are associated with the target user's ID, ensuring that only the intended recipient can respond.
* **TTL Enforcement (Time-To-Live):**\
  Each invitation includes a **TTL (Time To Live)** parameter, defined in seconds. This TTL dictates the **validity window** for the invitation. If the TTL expires before the invited user accepts, the system no longer guarantees successful entry—even if the user attempts to join.
* **Join Operation:**\
  Upon receiving an invitation, the recipient can invoke the **Join API** to request admission. The server evaluates the session's current member count and the invitation's TTL status before admitting the user.

This design supports **secure, time-bound session access** while maintaining control over **maximum membership limits** and **session integrity**. For implementation guidance and TTL configuration options, refer to the **Diarkis Server API documentation**.

### Accepting Invitations

Users who receive a **Session invitation** may join the associated Session by **explicitly accepting the invitation** and invoking the **`Join()` API** call. This operation validates the invitation parameters—including its **target user ID**, **session identifier**, and **TTL (Time-To-Live)**—before granting access.

Once validated, the user is added to the Session's active member list, provided the **maximum member capacity** has not been exceeded. This controlled entry mechanism ensures **secure, session-scoped participation** and maintains integrity across distributed session states.

Refer to the **Diarkis Server API documentation** for method signatures and required parameters.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.diarkis.io/en/diarkis-modules/session.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.