Session Host Service

The Session Host (started as a backend with webstream.exe -backend) is the private application server — the unit of compute that scales with concurrent sessions. It manages a pool of Windows RDP sessions, launches a Streamer inside each one, and registers itself with the Gateway so traffic can be routed to it.

Function

• Session pool management. Provisions and recycles Windows pool accounts (e.g. webs01, webs02), creating an RDP session per user connection and tearing it down — with profile cleanup and NTFS ACL enforcement — when the session ends.
• Streamer launch. Each RDP session runs its own webstream.exe streamer instance, launched at session logon; the Session Manager hands it its session UUID and command line over the /control WebSocket protocol.
• Connection brokering. Answers /getConnection (proxied from the gateway) by allocating a pool session and returning the streamer's port so the browser's WebSockets can be proxied through.
• Gateway registration. Registers on startup, heartbeats every 10 seconds with live capacity and load figures, and unregisters on shutdown.
• Static content. Serves the httpdocs web client over plain HTTP on the private network (the gateway terminates SSL).

Ports and endpoints

In standalone Session Manager mode (-sm, without a gateway) the service also opens a /control WebSocket on basePortNumber (9000) and HTTP on 9001. Production deployments use -backend, where the gateway proxies WebSockets directly to streamers instead.

Message contracts

Outbound — to the Gateway

Inbound — from the Gateway

Local — Session Manager ↔ Streamer (WebSocket text protocol)

Session start queue

Starting a session is disk-intensive: profile, registry, and hive preparation followed by an RDP logon that loads NTUSER.DAT. Running several of these at once causes disk-IOPS contention that can thrash competing starts and destabilise sessions already running, so the start phase is strictly serialised through a gate with capacity fixed at 1 (by design, not configurable).

• Non-blocking. /getConnection never waits on the gate. A queued session is registered immediately in state QueuedForPrep and the browser polls, showing preparing, until its FIFO turn completes. The client is told its queue position.
• Bounded. Beyond maxQueuedStarts a new launch is rejected with START_QUEUE_FULL — an honest “try again later” beats promising an unboundedly long serial wait.
• Abandoned waiters. A queued start whose browser stops polling for abandonSeconds (tab closed, navigated away) is cancelled rather than burning a gate slot on a session nobody is waiting for.
• Watchdog. A wedged head-of-queue start is failed after prepWatchdogSeconds and the gate released, so one stuck logon cannot stall every start on the host.
• Settle window. After a successful logon the gate is held for settleSeconds while Windows spins up per-user services and the shell at high CPU, smoothing resources before the next start begins.

The queue is tuned by the optional <sessionStartQueue> element inside <webstreamSettings> in app.config.xml. If the element is missing, the defaults below apply.

Configuration

Aligned settings on peer services

• The gateway's healthCheck.timeout (≥ 6 s recommended) and failureThreshold (≥ 3) must tolerate this host answering probes slowly during heavy login provisioning, or it will be flapped to Unreachable and workspace launches will fail.
• Streamers on this host read the same gateway.backend.gatewayUrl for their 15-second licence check-ins.
• metrics and activityLogging sections on this host determine what its streamers report to the Metrics Engine.