View source for Documentation:Streaming Client

A '''Streaming client''' (also called a '''Streaming app''') lets you build an interactive [[Documentation:MDriven Turnkey Architecture|Turnkey]] user interface from a [[Documentation:ViewModel|ViewModel]] while keeping the active ViewModel state and rule evaluation on the server.

A Streaming client is a client of the Turnkey server that uses the '''Streaming API'''. It maintains a local client-side representation of the information exposed by the ViewModel. The server maintains the active ViewModel information needed for that client in memory and subscribes to changes that can affect it.

== What a Streaming client does ==

A Streaming client does not need the full domain model. The ViewModel defines the perspective and information that the client may use for its task.

For example, a video-browsing ViewModel can expose a list of videos and a ''Browse'' action without exposing a way to edit a video's genre or inspect its viewing history. The client receives the ViewModel data needed to display and interact with that browsing screen; the server retains the application logic and processes the action.

{| class="wikitable"
! Responsibility
! Streaming client
! Turnkey server
|-
| Display and local interaction
| Holds a local representation of the ViewModel data and binds the user interface to it.
| Supplies the ViewModel data and changes.
|-
| User changes
| Sends user-generated changes and action requests to the server.
| Applies the changes and executes actions.
|-
| Rules and derived values
| Updates its local representation when it receives server changes.
| Re-evaluates affected ViewModel expressions and subscriptions, including [[Documentation:Learn OCL|OCL]] expressions.
|-
| Data sent after an update
| Applies the received changes to the local representation.
| Sends changes to the ViewModel rather than re-rendering the entire ViewModel.
|}

== How changes flow ==

The Streaming API exchanges changes in both directions. A user edit can change local client state, such as a checkbox value or entered text. The client sends that change to the server. The server combines it with the server-side ViewModel state, evaluates any affected dependencies, and returns the resulting ViewModel changes. The client applies those changes to its local representation, which updates the data-bound user interface.

For example, if a user changes a filter value:

# The client sends the changed filter value to the server.
# The server updates the corresponding server-side ViewModel state.
# Subscriptions detect that an expression used by the ViewModel is no longer current.
# The server re-evaluates the expression that produces the filtered list.
# The server sends the list changes to the client.
# The client updates its local list, and the bound interface reflects the new result.

This is a round trip, but it exchanges the changes that occurred rather than a complete re-rendered ViewModel. For a fuller discussion of the boundary between browser code, ViewModels, and server-side logic, see [[Documentation:High or low exposure to risk]].

== Available client implementations ==

The standard Turnkey web client is the [[Documentation:AngularJS Client|AngularJS client]]. It is an implementation of the Turnkey Streaming Client API.

A streaming implementation is not limited to the web client. The [[Documentation:Windows WPF client|Windows WPF client]] also maintains a local replica of the server ViewModel information tree, sends queued user commands to the server, and merges server changes into that replica.

You can create another client implementation for the Streaming API, but it must handle the client-side ViewModel representation and the exchange and application of server changes.

== Server memory and client lifetime ==

A Streaming app has an active server-side memory cost. For each active client that has a connection, Turnkey keeps an active memory space containing the information needed for that client. That state remains held while the client is active and connected.

This differs from a fully rendered MVC page. Turnkey can use an EcoSpace cache efficiently for MVC page renderings, but when a user moves to an Angular streaming page, the streaming client obtains an EcoSpace and holds it until the client leaves.

Plan for this when designing pages with many concurrent users:

* Use a Streaming client where the user benefits from interactive, data-bound updates.
* Use an MVC page when the page does not need to retain streaming server resources.
* Configure a timeout when inactive Streaming clients should be moved to a page that does not require those resources.

[[Documentation:Turnkey Client Timeout|Turnkey Client Timeout]] describes the server-wide and per-ViewModel timeout settings, including the built-in and customizable timeout page.

== Streaming and realtime notifications ==

Streaming keeps an active client synchronized with changes to its server-side ViewModel. [[Documentation:SignalR and Realtime|SignalR and Realtime]] can notify live Turnkey JavaScript clients that there is news to retrieve. When notified, a live client asks its Turnkey server for an update; the normal refresh process then evaluates and delivers any affected data.

Treat realtime notification configuration as a separate concern from defining the Streaming client and its ViewModel.

== See also ==

* [[Documentation:AngularJS Client]]
* [[Documentation:Windows WPF client]]
* [[Documentation:Turnkey Client Timeout]]
* [[Documentation:SignalR and Realtime]]
* [[Documentation:High or low exposure to risk]]

[[Category:Intermediate-Friendly]]
[[Category:MDriven Turnkey]]
[[Category:Priority 50]]
[[Category:Turnkey Architecture Overview]]