Session trees
A session tree is a virtual view of the topic tree presented to a session by fetch and subscription operations. A custom session tree can be configured and maintained based on a session's properties. This can be useful for security, optimisation, personalisation and localisation.
Session trees overview
Session trees enable your application to present tailored data to each client session. By using session trees, you can present each session with a subset of the full topic tree based on its session properties. This enables tailored data to be served to a session even if it is not authenticated. For example, you could localize your application by showing different data to a session based on its $Country session property.
Session trees are configured using a set of declarative rules maintained by the server. You can create or change the rules using one of the client SDKs.
Session trees complement the data transformation capabilities of topic views. Topic views enable you to create new branches of the topic tree from existing branches; session trees enable you to tailor which branches a session can access.
Branch mappings and session paths
A session tree is produced by applying branch mappings to the topic tree. Branch mappings are organised into branch mapping tables. Each branch mapping table is assigned to a unique path: the session tree branch.
A session tree is composed of session paths. Each session path is mapped via the branch mapping tables to a unique topic path.
A branch mapping table is an ordered list of (session filter, topic tree branch) pairs. For example, the branch mapping table for the session tree branch market/prices might be:
| Session filter | Topic tree branch |
|---|---|
| USER_TIER is '1' or $Country is 'DE' | backend/discounted_prices |
| USER_TIER is '2' | backend/standard_prices |
| $Principal is '' | backend/delayed_prices |
With this configuration, if an unauthenticated session (one that matches the $Principal is '' session filter) subscribes to the session path market/prices/X, and there is a topic bound to the topic path backend/delayed_prices/X, the subscription will complete. The session will receive a subscription notification under the session path market/prices/X, together with the topic properties and the value of the topic. The session is unaware that the data originates from a topic bound to a different topic path. If no topic is bound to backend/delayed_prices/X, the subscription will not resolve and the session will receive no data, even if there is a topic bound to market/prices/X.
Session trees complement the data transformation capabilities of topic views. In our example, the time delayed time feed at backend/delayed_prices could be maintained by a topic view using the delay by clause.
Branch mappings are persisted by the server and shared across a cluster, in a similar manner to topic views, security stores, and metric collectors. Branch mappings are editable using this feature, and via the management console.
For a given session and session path, at most one branch mapping applies. The applicable branch mapping is chosen as follows:
- Each branch mapping table with session tree branch that is a prefix of the session path is considered. For a given table, the first branch mapping with a session filter that matches the session's properties is the one that applies. A branch mapping table may have no applicable branch mappings for a session.
- If there are several such branch mapping tables with a branch mapping that for the session, the one with the longest prefix of the session path applies.
- If no branch mapping table has a branch mapping for the session, the session path is translated to the identical topic path.
Access control
To subscribe to or fetch from a session path, a session must be granted the appropriate path permission to the session path for the operation (SELECT_TOPIC, or READ_TOPIC). The session doesn't require any permissions to the topic path of the topic providing the data.
To create or replace branch mappings, a session needs the MODIFY_TOPIC path permission for the session tree branch of the branch mapping table, EXPOSE_BRANCH path permission for the topic tree branch of each branch mapping, and (if an existing table with the same session tree branch is being replaced) EXPOSE_BRANCH permission for each branch mapping of existing table.
To retrieve a branch mapping table, a session needs the READ_TOPIC path permission for its session tree branch.