Network Working Group Christopher Ross
Internet-Draft Independent
Intended status: Experimental 17 November 2026
Expires: 21 May 2027
Mercurius Window System (MWS)
draft-ross-mercurius-08
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at
any time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This document is an individual submission to the IETF. Distribution
of this document is unlimited.
This Internet-Draft will expire on 21 May 2027.
The latest version of this draft can be found at:
https://mercurius.tebibyte.org/draft-ross-mercurius.txt
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with
respect to this document. Code Components extracted from this
document must include Revised BSD License text as described in
Section 4.e of the Trust Legal Provisions and are provided without
warranty as described in the Revised BSD License.
Abstract
The Mercurius Window System (MWS) is a zero-trust, network-native
window system for contemporary desktops. It combines persistent,
detachable graphical Sessions with network transparency. MWS works
on a workstation without requiring network connectivity. The same
Session model allows users to start a new Session or resume a
detached Session, either at the workstation itself or from another
device across the network.
MWS complements local display systems such as Wayland. Applications
and their state remain on the workstation, while a Portal provides
the user's display and input facilities. Modern graphics APIs and
authenticated transport support this separation between where
applications execute and where a user interacts with them. This
document specifies the Session, Window, and communication behaviour
needed for independent implementations to interoperate.
Executive Summary (Non-Normative)
Mercurius is a zero-trust network-native window system intended to
bring network transparency to contemporary graphical desktops, while
making persistent Sessions useful on a single machine. A Session is a
collection of applications, Windows, and working state maintained by
a workstation. A user can explicitly detach from it and later return
to the same applications and Windows without starting them again,
subject to the workstation's policy.
Zero-trust means that neither a device's location nor possession of
that device establishes authority to access the workstation. Users
authenticate before attaching to a Session, and the workstation
validates requests against that Session's permissions and resources.
These rules apply equally at the local console and across the
network.
For example, a user may keep separate Sessions for development and
other tasks, detach from one, and resume another. This works at the
workstation's own console without any network connection. Connecting
from another device extends the same arrangement: the Session remains
on its workstation, and the user can resume it from wherever a
suitable Portal is available. Network transparency means that local
and network access share the same Session behaviour.
A Portal is the software and local facilities through which the user
sees Windows, hears audio, and supplies input. It may run on the
workstation itself or on another computer. Applications execute and
render on the workstation; the Portal presents their output and
returns the user's input. Changing Portals changes the place from
which the user accesses a Session, while its applications and working
state remain on the original workstation.
Mercurius complements Wayland and other local display systems. A
Portal can use Wayland to display application Windows alongside other
Windows on the local desktop and to receive keyboard and pointer
input. Mercurius supplies the Session continuity and workstation
access, while the local display system handles presentation and
interaction at the user's device. Network use is a capability of this
window system; its Session model also applies when everything runs
locally.
Detachment explicitly requests preservation of a Session; an
unexpected disconnection instead starts a bounded reconnection grace
period. The remainder of this document defines the communication and
state-management rules that implement this model.
Table of Contents
1. Introduction
1.1. Scope and Applicability
1.2. Design Rationale
1.3. Cloud and Distributed Computing Context
1.4. High-Performance Rendering and Gaming
1.5. Portal Requirements and Wireless Considerations
1.6. Session Mobility and Detachable Operation
2. Conventions Used in This Document
2.1. Requirements Language
2.2. Referenced Terminology
2.3. General Terminology
2.4. Protocol Roles
2.5. Additional Terms and Threat-Model Names
2.6. Wire-Format Conventions
3. System Architecture
3.1. Architectural Principles
3.2. Protocol Endpoints
3.3. Workstation-Centric Model
3.4. Rendering and Surface Model
3.5. Session Model
3.6. Zero-Trust Portal Model
3.7. Network Considerations
3.8. Transport Requirements
4. Detailed Architecture
4.1. Sessions
4.2. Seats
4.3. Windows
4.4. Server Window Management
4.5. Rendering Model
4.6. Audio Model
4.7. Stream Allocation
4.7.1. Session Identity and Message Routing
4.8. Session Lifecycle
4.9. Session and Seat Model
4.10. Local Transport Profile (Non-Normative)
4.11. Security Model
4.12. Clipboard Model
5. Protocol Specification
5.1. Message Framing
5.1.1. Transport Fragmentation
5.2. Control Messages (Stream 0)
5.2.1. Initial Handshake (001-099)
5.2.1.1. Session Identifier Semantics
5.2.2. Session Management (100-199)
5.2.2.1. Resume Semantics
5.2.2.2. Clipboard Exchange
5.2.2.3. Session D-Bus Bridge
5.2.3. Window Lifecycle (200-299)
5.2.3.1. Window Identifier Scope
5.2.3.2. Desktop Decoration
5.2.3.3. Desktop Task Model
5.2.3.4. Desktop Component Delegation
5.3. Rendering Messages (300-399)
5.4. Input Plane (400-499) -- Stream 2
5.4.1. Pointer Motion Events
5.4.2. Keyboard Events
5.4.3. Text Input Events
5.5. Video Presentation (500-599)
5.6. Audio Plane (600-699) -- Stream 4
5.6.1. Session Media Timeline
5.7. Protocol State Machine
5.7.1. Initial Connection
5.7.2. Session Resume
5.8. WSI Extension (Surface Creation)
5.8.1. Surface Binding and Session Validation
5.8.2. Vulkan Extension Registration
5.9. Error Handling (700-799)
5.9.1. Session and Resource Validation Errors
6. Implementation Guidance
6.1. Endpoint Independence
6.2. Portal Processing Model
6.3. Concurrency and Backpressure
6.4. Version Scope
6.5. Reference Implementation Components
6.6. Usage Examples
6.6.1. SSH and MWS
6.6.2. Session Selection
6.6.3. Detach and Resume
6.6.4. Local and Remote Portals
6.6.5. Independent Portals
7. Implementation Requirements and Validation
7.1. Test Matrix
7.1.1. Core Validation Tests
7.2. GPU Isolation Requirements
7.3. Bandwidth and Transport Isolation Requirements
8. Performance Considerations
9. Security Considerations
9.1. DANE Deployment (Non-Normative)
10. IANA Considerations
11. Acknowledgements
12. References
12.1. Normative References
12.2. Informative References
Appendix A. MWS Opcode Registry
A.1. Handshake and Authentication (000-099)
A.2. Session Management (100-199)
A.3. Window Lifecycle (200-299)
A.4. Rendering Messages (300-399)
A.5. Input Plane (400-499)
A.6. Video Plane (500-599)
A.7. Audio Plane (600-699)
A.8. Error Reporting (700-799)
A.9. Transport Services (800-899)
A.10. Experimental and Vendor-Specific (900-999)
Appendix B. Authentication Mechanism Registry
B.1. Standard Mechanisms
B.2. Extensible Mechanisms
B.3. Private and Experimental Mechanisms
B.4. Registration Policy
Appendix C. SCTP Stream Usage Summary
C.1. Stream 0 -- Control Plane
C.2. Stream 1 -- Rendering Messages
C.3. Stream 2 -- Input Plane
C.4. Stream 3 -- Video Plane
C.5. Stream 4 -- Audio Plane
C.6. Stream 5 -- Bulk
C.7. Additional Streams
Appendix D. Protocol State Machine Diagrams
D.1. Initial Connection State Machine
D.2. Session Resume State Machine
D.3. Error Handling State Machine
D.4. Stream Interaction Summary
Author's Address
1. Introduction
The Mercurius Window System (MWS), named for Mercurius, the Roman
messenger god of swift communication, is a secure window system for
both local and remote use. A user may work directly at the console of
a workstation as on a conventional Unix-like desktop, with full
access to its GPU, input devices, audio devices, and local display.
The same session may also be accessed from lightweight, mobile, or
untrusted portal devices elsewhere, without replicating the
workstation's software environment or exposing its data or GPU
resources. Compute, storage, rendering, and audio processing remain
on the workstation; Portals provide authenticated display, input, and
audio endpoints.
MWS is intended to let a workstation remain itself while being
reached from elsewhere. The workstation is treated as a long-lived
environment that accumulates tools, history, and identity; remote
devices are simply places from which the user inhabits that
environment. A user may begin work at a powerful machine in the
office and later continue the same session from a laptop, thin
portal, or secondary desktop in another location, without maintaining
multiple environments or synchronising state. Remote access is an
extension of the local workstation rather than a separate mode of
operation.
MWS is not merely a remote framebuffer protocol. It defines
structured, message-oriented semantics for presence, Sessions,
Windows, input, audio, and rendering state on a workstation. Even
when carrying presented pixel buffers, it preserves the identity,
ownership, geometry, lifecycle, and routing of each Window. The
Transport is optimised for SCTP's multi-stream, message-oriented
semantics [RFC9260], with separate streams assigned or reserved for
control, rendering, input, video, and audio.
This architecture continues the lineage of early Unix window systems
such as X11, which supported network-transparent interaction with
applications running on central servers, while applying modern
zero-trust security [NIST800-207], authenticated multi-stream
transport [RFC9260][RFC4895], and GPU isolation. Earlier systems such
as NeWS also explored server-side rendering. Wayland defines direct
interaction between applications and a local compositor, including
shared rendering buffers [WAYLAND]. MWS instead specifies
authenticated network attachment and Session continuity between a
workstation and a Portal, while preserving local operation.
1.1. Scope and Applicability
This document specifies the Mercurius Window System (MWS) protocol,
the transport-level protocol used by MWS to establish, authenticate,
and maintain a user's graphical presence on a workstation. The MWS
protocol defines Message framing, authentication, Session attachment,
Window lifecycle, and rendering presentation over a secure transport
profile based on DTLS 1.3 [RFC9147] over SCTP [RFC9260], using the
mapping defined by [I-D.6083BIS]. It specifies the semantics and
requirements of the input, video, and audio planes. Where this
version does not define a payload encoding, it explicitly prohibits
senders from emitting the affected Message.
MWS is intended for environments where:
* applications execute on a central workstation or server
* users may work locally at the console or remotely from other
devices
* portals may be untrusted, mobile, or ephemeral
* users may relocate sessions across devices
* GPU-accelerated workloads must remain server-resident
* audio capture and playback must remain server-resident or
explicitly brokered
* network transparency is a first-class requirement
* loss or theft of a device must not compromise workstation security.
MWS does not replace local display protocols such as Wayland, nor
does it extend them. It provides a complementary mechanism for secure
local and remote presence in multi-user and distributed environments
where local display protocols do not apply.
1.2. Design Rationale
Early Unix window systems, including X11, were explicitly designed
for network transparency: applications executed on powerful central
servers while users interacted from remote terminals. This model
proved valuable in multi-user and distributed environments. MWS
retains network transparency while specifying authenticated,
Session-scoped authority and server-side validation of Portal input
and resource references.
Wayland combines display-server and compositor responsibilities and
permits direct Client rendering into shared buffers [WAYLAND]. MWS
defines the separate workstation-to-Portal boundary, with explicit
network transport and Session attachment semantics. This distinction
does not preclude a Wayland compositor from offering its own remoting
facilities or serving as a Portal's native display system.
MWS intentionally revives and modernises the network-transparent
workstation model. It retains the architectural advantages of
centralised execution and remote interaction while adopting a
zero-trust security model based on DTLS 1.3 [RFC9147], authenticated
SCTP [RFC9260][RFC4895] streams, and per-portal GPU isolation.
Rendering is server-resident and GPU-accelerated; Portals receive
presentation Messages produced by the workstation, and audio is
carried as explicit timestamped streams rather than device-local side
effects. All compositor policy, input routing, and window management
occur on the server, ensuring multi-user correctness and preventing
privilege escalation.
Crucially, possession of a portal device is never sufficient to
access the workstation. Session resume requires fresh user
authentication. Authoritative application data remains on the
workstation; the limits of protection against a compromised active
Portal are described in Section 3.6.
The result is a window system that provides deterministic semantics,
strong isolation, and relocatable sessions, enabling users to inhabit
remote workstations with the performance and responsiveness of a
local environment, whilst preserving first-class local console
operation.
1.3. Cloud and Distributed Computing Context
Many organisations operate private cloud or workstation-cluster
environments where users access centralised compute and GPU resources
from Portals on fixed or mobile devices. Public cloud deployments
exhibit similar characteristics: applications execute on remote
servers while portals roam across untrusted networks.
MWS aligns with this model by centralising execution and distributing
only the user interface. This avoids the inefficiencies of
distributed compute systems whilst preserving the benefits of remote
access, session mobility, and strong isolation between users. Because
portals are untrusted, MWS confines each authenticated association to
its authorised Session. A compromised active Portal remains a risk to
its user, as described in Section 3.6.
1.4. High-Performance Rendering and Gaming
MWS is primarily intended for workstation and private-cloud
deployments in which portals connect over well-provisioned LANs and
VPNs, typically with DANE [RFC6698][RFC7671] authenticating DTLS 1.3
[RFC9147] carried over SCTP as defined by [I-D.6083BIS]. In these
environments, modern GPUs provide hardware-accelerated AV1 encoding
[NVENC], which could support a future encoded-video profile. This
revision defines a fixed-size negotiated Video presentation profile,
with decoding requirements specified in Section 5.5. All workstation
rendering in MWS is performed using the Vulkan [VK14] API.
Nevertheless, the same architecture could accommodate
high-performance remote rendering workloads, including interactive 3D
applications and games. Support for such workloads is a stretch goal
rather than a primary target, but these use cases inform the design
of the transport, security, and rendering model to ensure that MWS
remains viable for demanding graphical applications.
1.5. Portal Requirements and Wireless Considerations
MWS portals are treated as untrusted endpoints. Practical deployments
assume a minimum level of capability. A typical portal is expected to
provide a modern CPU, a GPU capable of hardware-accelerated decoding
of a supported Video format, and at least gigabit-class network
connectivity. Higher resolutions or refresh rates benefit from
greater bandwidth, but MWS remains usable at reduced quality on
lower-capacity links.
Wireless performance depends on contention, interference, signal
quality, and the complete network path. Implementations should
measure available throughput and latency rather than infer
interactive performance from a wireless standard or advertised link
rate.
1.6. Session Mobility and Detachable Operation
Because sessions in MWS are server-resident and independent of portal
connections, the system naturally supports detachable operation. A
user may disconnect from one portal and later resume the same session
from another device, with all windows, GPU state, and compositor
context preserved.
This model is conceptually similar to terminal multiplexers such as
screen or tmux, but applied to a full GPU-accelerated graphical
environment. Session mobility is a core design goal of MWS and
informs its authentication, transport, and rendering architecture.
Deployments are expected to configure a reconnection grace period so
that brief network outages or short unscheduled breaks, such as those
needed to move or charge a portal device, do not cause the user's
Session to be lost.
2. Conventions Used in This Document
2.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
2.2. Referenced Terminology
Terminology relating to Vulkan follows the definitions and naming
conventions of the Vulkan 1.4 specification [VK14].
Terminology relating to SCTP follows the Stream Control Transmission
Protocol specification [RFC9260]. Terminology relating to DTLS 1.3
follows the Datagram Transport Layer Security specification
[RFC9147].
2.3. General Terminology
Unless otherwise stated:
* "workstation" refers to the host system on which Applications
execute. It includes the operating system, files, GPUs and other
local resources used by those Applications and the Server.
* "server" refers to the MWS protocol endpoint running on the
workstation, rather than to the host system as a whole. The Server
maintains authoritative Session state and applies MWS policy. The
reference implementation provides this role through the mwsd
daemon. References to the Workstation concern the host environment;
references to the Server concern its MWS protocol responsibilities.
* "portal device" refers to the physical device through which a user
interacts with the workstation. Examples include laptops, tablets,
phones, dedicated terminals, and embedded devices.
* "Portal" refers to the user-facing MWS endpoint: either the portal
device as a whole or the MWS Portal software (mwsc) running on it,
as the context requires. The Portal displays output, captures user
interaction, communicates with the Server, and provides a Seat for
a Session. It is not a Client.
* "session" refers to a persistent graphical environment maintained
on the workstation independently of portal connections.
* "association" refers to a transport-bound communication channel
between a portal and the server. When SCTP is used as the
transport, an association corresponds exactly to the SCTP
association defined in [RFC9260] and is identified by the SCTP
implementation's assoc_id. An association is ephemeral and exists
only for the lifetime of the underlying transport connection.
* "seat" refers to a set of input devices and output mappings
associated with a session and bound to a portal.
* "surface" refers to a drawable region managed by the compositor and
rendered by the workstation's GPU.
2.4. Protocol Roles
The following capitalised names identify MWS protocol roles and
resources. They describe protocol endpoints, authority, and
addressing; they do not prescribe an implementation's internal object
model:
* "Message" is one complete, addressed MWS message exchanged by
protocol endpoints.
* "Client" is an application running on the workstation on the user's
behalf, such as radialblur. A Client creates and renders Windows
within the user's Session. It is distinct from both the Library and
the Portal.
* "Library" is the complete workstation-local adaptation subsystem
between a Client and the Server. It presents the ordinary graphical
APIs expected by an unmodified Client and carries the resulting
Messages over the local client channel. An implementation may
divide this role between compatibility interposition and underlying
protocol facilities. An ordinary, unmodified Client need not know
about, call, or link against Mercurius.
* "Server" is the MWS protocol endpoint on the workstation. It is
authoritative for Sessions, Windows, resources, and policy.
* "Application" identifies a Client through its authenticated local
client channel at the Server. An application_id is a non-zero,
Session-scoped identifier assigned by the Server for this purpose.
It is not a process identifier or an implementation object pointer.
* "Window" is a Session-scoped graphical window, including a
top-level, transient, or popup Window. Lowercase "window" retains
its ordinary graphical meaning.
* "Session" is one authenticated user's server-resident graphical
environment and the resources within it.
* "Transport" is the protocol service that carries complete MWS
Messages between a Portal and the Server. Transport-reserved
Messages are exchanged only between peer transport endpoints.
Conforming implementations MAY organise their internals in any
manner, but MUST preserve the specified Message semantics, authority
boundaries, addressing, and routing.
2.5. Additional Terms and Threat-Model Names
* "command stream" refers to the structured Mercurius protocol
messages exchanged on SCTP stream 0 (control stream).
* "video surface" refers to a Window presented using a negotiated
encoded Video format as specified in Section 5.5.
* The names Alice, Bob, Eve, and Mallory are used in their standard
roles from security literature. Alice and Bob denote honest users,
Eve denotes a passive eavesdropper, and Mallory denotes an active
attacker. These names are used solely for threat-model examples and
do not correspond to real users or implementation artefacts.
2.6. Wire-Format Conventions
Wire formats are described in terms of octets and fixed-width
integers. C structures, C type names, alignment, padding, and host
byte order are not part of the protocol.
All multi-octet integers are transmitted in network byte order unless
explicitly specified otherwise. Signed integers use two's complement
representation. Lengths are measured in octets. Receivers MUST
validate lengths, reserved fields, and arithmetic before allocating
storage or using a payload. Unless explicitly allowed, trailing
octets are invalid.
Unless otherwise specified, text fields in MWS messages are encoded
as length-prefixed UTF-8 [RFC3629] strings ("Pascal strings"). A
length-prefixed string consists of an unsigned length field (for
example, a one-octet or two-octet unsigned integer) followed
immediately by that many octets of UTF-8 text. No NUL terminator is
transmitted on the wire; the length is authoritative.
Opaque variable-length fields use the same representation: an
explicitly sized unsigned length field followed immediately by that
many octets. Opaque fields are not implicitly text, do not carry a
terminator, and have no alignment padding.
3. System Architecture
This section provides a high-level overview of the Mercurius Window
System (MWS). It describes the conceptual model, major components,
and architectural principles that inform the detailed design in
Section 4 and the protocol specification in Section 5.
MWS is designed around a workstation-centric model in which all
rendering, compositing, audio processing, session management, and
window-management policy reside on a central server. Portal devices
act solely as authenticated display, audio, and input endpoints. This
model preserves the semantics of a local workstation while enabling
secure remote presence across modern networks.
MWS assumes portal devices with at least gigabit-class connectivity,
including modern Wi-Fi networks that routinely exceed 1 Gb/s. The
protocol is optimised for 10 GbE LANs, where uncompressed or lightly
compressed surfaces, high-motion content, and low-latency audio can
be delivered with minimal delay. Devices with substantially lower
bandwidth may operate at reduced quality but are not a primary design
target.
The Audio Plane uses a dedicated stream suitable for
workstation-class media workloads. This revision defines negotiated
L16, L24 and F32 linear PCM playback and capture lifecycles. It does
not make quantitative latency guarantees.
3.1. Architectural Principles
The design of MWS is guided by the following principles:
* Applications execute on a central workstation or server.
* Local and remote interaction share identical session semantics.
* Portal devices may be untrusted, mobile, or ephemeral.
* Users may relocate sessions across devices without restarting
applications.
* GPU-accelerated workloads remain server-resident.
* Real-time audio is a first-class subsystem with strict latency
and ordering requirements.
* Network transparency is a first-class requirement.
* Loss or theft of a portal device must not compromise workstation
security.
These principles reflect the goal of treating the workstation as a
long-lived environment with continuity of storage, configuration, and
identity.
Alternative transports such as QUIC were considered. However, SCTP's
native multi-streaming, message-oriented delivery, and support for
partial reliability align directly with the requirements of MWS.
QUIC's multiplexed byte-stream model, together with the absence of
partially reliable streams, would require additional framing and
scheduling logic to emulate SCTP semantics. For these reasons, SCTP
is the primary transport for MWS.
The protocol's guarantees depend on transport properties that SCTP
provides natively, including independent ordered streams,
preservation of message boundaries, optional partial reliability,
avoidance of cross-stream head-of-line blocking, and stable SCTP
associations. These properties are required to ensure deterministic
compositor behaviour, responsive input under load, support for
high-motion video surfaces, low-latency audio transport, relocatable
sessions, and multi-seat concurrency.
TCP does not provide these properties without substantial additional
protocol machinery. A TCP-based transport would therefore be unable
to meet the latency, isolation, and concurrency requirements of MWS
as defined in this document, and is out of scope for this
specification.
3.2. Protocol Endpoints
MWS has two network protocol endpoints: the Server on the workstation
and the Portal on the user's portal device. The Server maintains
authoritative Sessions, Windows, rendering, focus, input routing, and
policy. The Portal presents graphical and audio output and sends user
input to the Server.
A workstation Client uses its ordinary graphical APIs. The MWS client
library transparently adapts those calls to the local client channel
to create Windows and provide rendering content. The complete path is
Client -> Library -> Server -> Portal, and the reverse path applies
to Portal-originated interaction and server notifications. The client
channel is distinct from the authenticated Portal association and
carries only Messages whose definitions explicitly permit that scope.
This specification does not prescribe how an implementation divides
these responsibilities among internal components.
3.3. Workstation-Centric Model
The workstation is the authoritative environment. It owns all GPU
resources, logical audio devices, compositor state, and input-routing
policy. Applications run exclusively on the workstation, and all
rendering and audio processing are performed on workstation-resident
hardware.
Portal devices own their physical input hardware. Input events are
generated on the portal and forwarded to the workstation, which
applies focus, routing, and seat semantics. The workstation never
interacts with the portal's physical devices directly; it operates
only on the logical input events they produce.
GPU resources are exposed to MWS exclusively through the Vulkan API.
The workstation enumerates all available GPUs using
vkEnumeratePhysicalDevices() and creates one compositor instance per
physical device in the reference implementation. An interoperable
implementation may organise its GPU resources differently. No Vulkan
object or native handle is transmitted to a Portal.
Audio resources are exposed to MWS through audio devices, each of
which represents a physical or virtual playback or capture endpoint.
Audio streams are created dynamically to transport PCM audio between
the workstation and portal devices.
A user may interact with the workstation in two ways:
* Local console mode, using the workstation's own keyboard,
pointer, display, and audio hardware.
* Remote presence mode, using an authenticated portal device
elsewhere on the network.
Local and remote interaction share the same compositor, window tree,
audio devices, and session state. Remote presence is an extension of
the local workstation, not a separate mode of operation. Sessions
persist across transient disconnections, but long-term persistence
requires explicit detachment.
3.4. Rendering and Surface Model
The MWS architecture distinguishes two classes of graphical output:
* rendering updates, representing Window content prepared for
presentation by the Portal
* video surfaces, carrying fixed-size negotiated Video content as
specified in Section 5.5
This revision defines pixel-based rendering updates and negotiated
Video presentation. The Server may encode ordinary Window content as
Video, or an Application may supply encoded content explicitly.
Surfaces represent drawable regions within the server's graphical
environment. Windows reference one or more surfaces. The compositor
prepares ordinary rendering for Portal presentation; Applications may
instead explicitly supply encoded access units through Section 5.5.
The Server may also produce those access units from ordinary Window
content. When ordinary Render content falls back to Video, the Server
encodes that content using its hardware codec facilities. The Portal
decodes and presents Video using its GPU. Application-supplied
encoded content does not require the Server to encode it again.
3.5. Session Model
Sessions are server-resident and persist independently of portal
connections, but long-term persistence requires explicit detachment.
MWS tolerates transient network interruptions; if a portal reconnects
within the configured grace period, the session continues without
interruption. If a portal disappears without detaching, the session
is preserved only for the duration of this grace period. Once the
period expires, the session is closed, and applications terminate in
the same manner as they do in a workstation session without an active
seat. Because all application, window, and session state resides on
the workstation, failure, loss, or destruction of a portal device
does not by itself risk loss of in-progress work; the session remains
intact on the server and may be resumed from another device, subject
only to the reconnection grace period.
A user may explicitly detach a session to preserve it beyond the
reconnection grace period and may later resume it from any authorised
device. A single transport association may provide multiple Seats
when an applicable extension defines them and local policy permits.
The precise rules governing how many transport associations may
attach to a session over time, and under what conditions, are defined
in Section 4.8.
Sessions contain Seats, each of which aggregates input devices, audio
streams, and presentation state for a particular user interaction
context. Multiple Seats may be active concurrently when an applicable
extension defines their attachment and routing. This revision defines
only the base Seat; it does not grant another user or Portal
association access to the Session.
This model enables mobility across devices while preserving the
semantics of a traditional workstation and avoiding long-lived
orphaned sessions.
3.6. Zero-Trust Portal Model
All portal devices are treated as untrusted endpoints, even on local
LANs. Trust is established exclusively through cryptographic identity
and explicit authorisation rather than network location. A portal
device is not an identity and is not authorised to access a session
by virtue of its presence on the network; only the user is
authorised.
A Portal's location and native display system do not establish its
authority. MWS derives that authority from the authenticated user and
confines it to the attached Session. The Server must validate each
operation even when the Portal is on the local network or
workstation.
Server identity is established during the DTLS 1.3 handshake carried
over SCTP for each transport association. Deployments SHOULD use
DNS-Based Authentication of Named Entities (DANE) [RFC6698][RFC7671]
to bind the server's certificate to DNSSEC-protected TLSA records,
allowing portals to verify that they are communicating with the
correct workstation without relying on public certificate authorities
or assumptions about local network topology.
User authentication is performed at the application layer using the
mechanism-agnostic model defined in Section 5.2.1. The server
advertises supported mechanisms (for example, "PAM", "FIDO2"), and
the portal selects one. This allows deployments to integrate
password-based, hardware-token, federated, or certificate-based user
authentication without modifying the protocol.
A portal device is assumed to be mobile and at risk of loss or theft.
User files and authoritative Session state remain on the workstation
and are not replicated to the Portal. A Portal may, however, hold
reusable authentication material such as an encrypted private key,
and an active Portal necessarily observes displayed content and user
input. A compromised active Portal can therefore compromise the user
operating it.
The zero-trust boundary is server-side authority. Possession or
compromise of one Portal MUST NOT grant authority over another user's
Session, reveal resources outside the attached Session, or make
Portal-supplied identifiers authoritative. Deployments that require
proof of user presence MUST choose an authentication mechanism that
provides it; the base protocol does not infer user presence merely
from possession of a device or private key.
3.7. Network Considerations
MWS is designed to operate over untrusted IP networks, including
public networks and variable-quality wireless links. The protocol
does not assume that portals are located on the same LAN as the
workstation, nor that any network segment provides meaningful
security. A portal on a local LAN and a portal on a remote network
are treated identically by the workstation.
MWS is designed for modern networks:
* 10 GbE provides optimal performance and headroom for multiple
high-resolution seats on a single workstation.
* Wi-Fi 6/6E/7 provides multi-gigabit throughput with variable
jitter and is fully supported for single-seat portals.
* 1 GbE provides a usable baseline for typical desktop workloads
and a small number of seats on a workstation.
* Sub-gigabit links are outside the primary design envelope and
are not expected to provide an acceptable experience for
high-resolution, high-refresh workloads or low-latency audio.
Rendering compression and pacing adapt presentation traffic to
available bandwidth, while stream scheduling prioritises Control,
Input, and Audio over bulk traffic. The negotiated Video profile in
Section 5.5 carries fixed-size negotiated Video surfaces.
The detailed architecture is specified in Section 4, and the wire
protocol is defined in Section 5.
3.8. Transport Requirements
MWS requires a transport that provides structured, message-oriented
delivery with support for multiple independently ordered channels.
The transport MUST preserve message boundaries, MUST support
concurrent streams with independent ordering, and SHOULD provide
mechanisms for partial reliability to avoid retransmission of stale
high-volume data such as video surfaces and real-time audio frames.
The transport MUST avoid cross-stream head-of-line blocking. Input
events, control messages, rendering updates, audio streams, and video
surfaces are logically independent flows, and the correctness of
compositor behaviour depends on their timely and ordered delivery
within their respective channels. A transport that enforces global
ordering across all data would introduce latency coupling between
these flows and would not meet the responsiveness requirements of
MWS.
A server carrying more than one association MUST apply backpressure
per association. Readiness of a shared transport endpoint MUST NOT be
interpreted as evidence that any particular association can accept
more data. A congested or stalled portal MUST NOT block transport
progress for other portals.
The transport MUST support stable associations that survive supported
path changes for the lifetime of the association. Mobility which
cannot preserve that association uses fresh authentication and
Session resumption. SCTP multihoming does not by itself guarantee
uninterrupted connectivity across arbitrary networks or NATs.
SCTP satisfies these requirements through its native multi-streaming
model, message-oriented delivery, optional partial reliability, and
support for multi-homing. These properties align directly with the
architectural principles defined in Section 3.1 and are required for
deterministic compositor behaviour, responsive input under load,
support for high-motion video surfaces, low-latency audio transport,
relocatable sessions, and multi-seat concurrency.
MWS protects SCTP user messages with DTLS 1.3 using the
DTLS-over-SCTP mapping defined by [I-D.6083BIS]. That work replaces
the DTLS 1.0 mapping specified by [RFC6083] with a mapping for DTLS
1.3. Unlike TLS over SCTP [RFC3436], the DTLS mapping preserves
message boundaries, unordered delivery, and PR-SCTP. The cited
mapping remains work in progress; this experimental profile depends
on the specific revision cited in Section 12.1, including its revised
SCTP-AUTH dependency.
WebRTC data channels [RFC8831] provide a related example of secure,
message-oriented transport for interactive applications. They combine
SCTP streams, reliable or partially reliable delivery, and DTLS
protection. Their discussion of stream priorities and large-message
interleaving is relevant to keeping bulk traffic from delaying
interactive traffic. These mechanisms share finite path capacity;
they do not replace congestion control or application backpressure.
The layering differs: WebRTC carries SCTP packets inside DTLS over
UDP using [RFC8261], whereas this MWS profile carries DTLS records
over SCTP using [I-D.6083BIS]. The WebRTC encapsulation restricts
SCTP associations to single-homed operation. It is not the transport
profile specified here. These references are informative and do not
introduce a WebRTC dependency or change MWS delivery requirements.
Both endpoints MUST negotiate the ALPN identifier "mws" [RFC7301]
during DTLS establishment and abort if it is not selected. The SCTP
association MUST provide at least six streams in each direction.
DTLS records use the MWS-over-DTLS PPID requested as TBD2 in
Section 10. MWS Control uses Stream 0, which it shares with DTLS
handshake and alert traffic; other MWS planes use their assigned
streams.
TCP does not provide these properties without substantial additional
protocol machinery. TCP offers only a single in-order byte stream,
lacks message boundaries, enforces global head-of-line blocking, and
provides no support for partial reliability or multi-streaming. A
TCP-based transport would therefore be unable to meet the latency,
isolation, and concurrency requirements of MWS as defined in this
document, and is out of scope for this specification.
4. Detailed Architecture
The Mercurius Window System (MWS) is structured around a central
server (mwsd) that owns all GPU resources, audio devices, input
routing, and compositor state, and a set of untrusted portal devices
that connect over a secure, message-oriented transport. Once
connected, a portal device acts as a portal providing a seat. This
section describes the architectural model of sessions, seats,
windows, rendering, and compositor behaviour. The wire protocol and
message formats are defined in Section 5.
4.1. Sessions
A session represents the complete graphical environment associated
with a single authenticated user, including windows, workspaces, GPU
resources, audio devices, and compositor state. Sessions are
server-resident and MAY persist independently of portal connections
when explicitly detached.
User identity is established during the application-layer
authentication phase of the handshake (Section 5.2.1). The
authenticated identity (for example, a local username, a portal
certificate subject, or a federated identity token) is mapped to a
local user account via the system's authentication framework (such as
PAM).
4.2. Seats
A Seat represents a set of input devices, audio streams, and an
output binding for a Session. The model allows multiple concurrent
Seats, but this revision defines only one base Seat attached through
the Session's single Portal association. Additional Seats require an
applicable extension and local policy permission.
Input belongs to a Seat, and the compositor routes it according to
seat-specific focus and pointer state. Section 5.4 defines the base
Seat and logical input devices. Additional Seats, device enumeration,
and seat-specific output and audio routing require an extension.
4.3. Windows
Windows are server-managed objects representing top-level application
surfaces, including related transient and popup Windows. Each window
belongs to exactly one session and is associated with one or more
rendering surfaces (structured swapchains or video surfaces)
depending on compositor policy.
Window identifiers are scoped to a session. A portal MUST NOT
reference or interact with windows belonging to any other session.
The server MUST enforce this isolation and MUST reject or ignore any
protocol message that attempts to target a window outside the
authenticated session.
4.4. Server Window Management
The Server maintains the global window tree, stacking order, focus,
workspaces, and output mappings for each session. It is responsible
for:
* applying window-management policy
* routing input events based on seat and focus
* managing swapchains and presentation timing
* selecting between rendering updates and video fallback
* revoking or reconfiguring windows according to policy
The Server SHOULD expose a user-visible mechanism to forcibly
terminate an unresponsive window. This mechanism is
implementation-defined (for example, a "kill window" gesture similar
to Ctrl-Alt-Esc in KDE).
The Server MAY revoke swapchains, reconfigure windows, or migrate
them between outputs according to local policy, resource constraints,
or security requirements. When a swapchain is revoked, the server
notifies the portal and MAY substitute a placeholder or video
surface.
The Server is responsible for isolating and coordinating its GPU and
output resources. The internal division of device contexts, queues,
swapchains, and associated GPU buffers is implementation-defined.
4.5. Rendering Model
Rendering in MWS is workstation-side. Clients use the workstation's
graphics APIs and GPU through the Library adaptation path. The Server
validates the resulting client-channel Messages and manages Window
presentation. The defined pixel Messages do not carry Vulkan command
buffers. Portals do not access workstation GPU resources directly.
Render is the default presentation for ordinary content. The Server
selects Video fallback when Transport cannot reasonably sustain the
required Render delivery. High motion alone does not select fallback.
Portal processing pressure calls for reducing presentation work; it
is not by itself a reason to switch to Video.
Applications may instead supply supported encoded Video content
through the Library under Section 5.5, subject to Server
authorisation, negotiation and resource limits. This does not require
Transport pressure or prior decoding into Render pixels.
Because rendering is server-resident, a stalled or misbehaving portal
cannot block the compositor. The server MAY revoke a window's
rendering resources, substitute a placeholder surface, or terminate
the portal if rendering deadlines are repeatedly missed.
The MWS specification assumes a modern explicit GPU API for rendering
and composition (for example, Vulkan [VK14]) and requires that all
rendering and presentation operations be performed through the
compositor's device-level abstraction. Portal devices are not
required to implement any graphics API.
4.6. Audio Model
The audio subsystem manages audio devices and audio streams between
the workstation and Portal devices. Audio is a first-class
architectural subsystem with strict latency and ordering
requirements. Its traffic is logically independent of rendering and
control traffic while sharing the secure, multi-stream Transport.
An audio device represents a physical or virtual playback or capture
endpoint on the workstation, such as speakers, headphones,
microphones, instrument inputs, multichannel mixers, loopback
devices, and virtual sinks. Devices are enumerated and managed on the
server. A Portal manages its own physical playback and capture
hardware and exposes only the negotiated logical streams to the
Server.
Logical audio streams are created dynamically to carry PCM samples
between the workstation and the portal. Each audio stream is bound to
a specific audio device and seat, and is direction-specific (playback
or capture). Workstation-originated playback uses the Session media
timeline; capture uses the Portal capture clock, as specified in
Section 5.6.1. The Portal maintains bounded playout buffers.
Playback streams carry audio from applications on the workstation to
the portal device for presentation. Capture streams carry audio from
portal-attached input devices to the workstation, where the audio is
delivered to the appropriate session and applications according to
policy. The server MAY apply policy to limit or redirect capture
streams (for example, to prevent inadvertent capture in shared
environments, or to restrict which multichannel devices are exposed
to a given session).
The Audio Plane uses Stream 4, separate from control, rendering,
input, and video. Its Message lifecycle and current payload
requirements are specified in Section 5.6.
4.7. Stream Allocation
MWS assigns SCTP streams by communication role:
* Stream 0: control
* Stream 1: rendering
* Stream 2: input
* Stream 3: video
* Stream 4: audio
* Stream 5: bulk
These assignments are fixed. A Window is identified by Message
addressing and is not assigned an SCTP stream. Multiple Windows may
therefore use the same rendering or video stream without changing
their identity, ownership, or routing.
Stream selection follows the role of a Message, not the kind of
resource it concerns or its opcode range. For example, Window
creation and geometry control use Stream 0, while pixel presentation
for the same Window uses Stream 1. Keyboard-focus transitions use
Stream 2 so that they are ordered with the Input events they govern.
Each Message definition specifies its stream; opcode groups do not
override that assignment.
Endpoints MUST assign distinct scheduling priorities in this order,
from highest to lowest:
1. Control (Stream 0)
2. Input (Stream 2)
3. Audio (Stream 4)
4. Render (Stream 1)
5. Video (Stream 3)
6. Bulk (Stream 5)
Bulk is a traffic class, not a minimum Message size: tiny and empty
Messages assigned to it still use Stream 5. Endpoints MUST service
Control and Input independently of deferred rendering and
presentation work. Separate stream ordering alone does not assign
priority: the sender must apply the priority policy when admitting
and scheduling traffic, and the receiver must preserve it in
processing.
These priorities prevent bulk work from becoming a processing
dependency of Control. They do not pre-empt bytes already transmitted
or eliminate shared congestion, path capacity, or transport-buffer
limits. Endpoints must also bound bulk work and apply backpressure so
that those shared resources do not defeat the priority policy.
Streams 6-15 are reserved for future standard assignments. Streams 16
and above MAY be used by experimental or vendor-specific extensions
as described in Appendix C.7.
4.7.1. Session Identity and Message Routing
Each transport association is attached to at most one portal session
at any point in time. A session MAY be attached to different
transport associations over its lifetime (for example, after
detachment and resume), but a given transport association MUST NOT
carry traffic for more than one session concurrently.
The server MUST treat the transport association (for example, an SCTP
association as defined in [RFC9260]) as the authoritative source of
session context for message routing. No portal-supplied field may
override the Session to which ordinary traffic is delivered. The
offered identifier in MWS_SESSION_RESUME_REQUEST is a selection
request, validated under Section 5.2.2.1, rather than routing
authority.
After successful user authentication, the Server creates a bootstrap
Session through which the Portal may interact with a Session selector
or another Session-selection interface. This specification does not
require a graphical selector. The bootstrap Session is the
association's active Session until the user either continues it as a
new Session or selects an existing Session as defined in Section 5.
Until bootstrap Session establishment completes, the Server MUST
reject non-handshake traffic as specified in Section 5.2.1.
For any message received on a non-zero stream, the server MUST:
* identify the session currently attached to the transport
association
* verify that the session is active
* dispatch the message to the subsystem corresponding to the
stream
* reject or ignore the message if it is malformed or references
resources outside the session
Messages referencing windows, seats, or other resources not owned by
the attached session MUST be rejected with MWS_ERROR_SESSION
(type=702, fatal=0).
Except for an authorised resumption request, a Message carrying a
session_id inconsistent with its association MUST be rejected with
MWS_ERROR_SESSION (type=702, fatal=0).
On an association with an active handshake but no established
Session, only the handshake and applicable error Messages are
permitted. A Message received after the association has been closed
MUST be discarded without allocating Session resources.
4.8. Session Lifecycle
A session is a long-lived server-side construct that persists
independently of any particular network connection. A session becomes
ACTIVE when a portal completes Session establishment as defined in
Section 5 and remains ACTIVE until it is detached, abandoned,
explicitly terminated, or reclaimed by policy.
Authentication creates a new bootstrap Session, but does not by
itself resume any existing Session. A Portal MUST explicitly request
either continuation of the bootstrap Session as a new Session or
resumption of a Session offered by the server. If an existing Session
is resumed, it atomically replaces the bootstrap Session on the
association and the server destroys the bootstrap Session. The server
MUST NOT reattach an existing Session solely on the basis of matching
user identity.
A portal MAY explicitly detach from an ACTIVE session. Detach
transitions the session from ACTIVE to DETACHED. In the DETACHED
state, it has no attached transport association. Its Clients,
windows, compositor state, audio stream state, and GPU resources
remain server-resident. DETACHED sessions MAY be resumed by any
authenticated portal device belonging to the same user, subject to
server policy.
When explicitly detaching a Session, the user MUST be able to request
either that its Clients continue executing in the background or that
they are suspended until a Portal resumes the Session. This is a
server-side user-interface and policy requirement: this revision does
not encode that choice in the empty MWS_SESSION_DETACH payload. The
Server MAY accept, reject, or override that request according to
policy, but MUST report the effective choice to the user and retain
it as Session state. The policy for an unplanned transition to GRACE
is server-defined. In either state, the Clients MUST remain present
and MUST NOT be restarted merely because the Session resumes. A
Server that permits background execution MUST define and enforce
appropriate resource, timer, and externally visible I/O policy.
Loss of the transport association (for example, network outage, SCTP
association failure, timeout, or portal crash) while a session is
ACTIVE does not immediately terminate the session. Instead, the
server MUST transition the session to a GRACE state and start a
reconnection grace timer. In the GRACE state, the session remains
active but has no attached portal. If a portal reconnects and
successfully resumes the session before the grace timer expires, the
server MUST transition the session back to ACTIVE and the session
continues without loss of state.
An accepted MWS_SESSION_CLOSE_REQUEST explicitly terminates the
Session currently attached to the requesting Portal association, as
specified in Section 5.2.2. It does not detach the Session or enter
GRACE, and the Server MUST NOT wait for the reconnection grace
period. ABANDONED describes the expiration path below; it is not a
required intermediate state for explicit termination.
A Server deliberately terminating an attached Session MUST attempt to
send MWS_SESSION_END as specified in Section 5.2.2 before closing its
association. This terminal transition is irrevocable: the Session
MUST NOT enter GRACE or DETACHED or be offered for resumption.
Failure to deliver the terminal Message does not undo termination; a
Portal which does not receive it cannot infer termination from
transport closure alone.
If the reconnection grace period expires without a successful resume,
the server MUST treat the session as ABANDONED unless the user has
explicitly detached it. ABANDONED sessions MUST be terminated and all
associated resources reclaimed. Implementations MUST provide a
configurable reconnection grace interval and SHOULD allow values
sufficient to tolerate brief network outages on typical Wi-Fi and WAN
links. Servers SHOULD return a specific error status when a resume
request targets an expired session.
Long-term persistence is an explicit, opt-in behaviour: a session
continues to exist beyond the reconnection grace period only if the
user has explicitly detached it or otherwise marked it for later
resumption. Implementations MUST NOT retain ABANDONED or stale
sessions indefinitely. The server SHOULD reclaim resources associated
with inactive sessions according to local policy (for example, idle
timeout, logout event, or administrative limits).
A Session MUST NOT have more than one attached transport association
(Portal instance) at a time in the base protocol. That association
provides the base Seat; additional Seats require an applicable
extension and remain subject to Server policy. An implementation MAY
provide a mechanism that allows
additional associations to attach to the same session (for example,
for technical support), but such behaviour is outside the scope of
this specification and MUST NOT alter the semantics defined for the
single-association model above.
4.9. Session and Seat Model
Sessions may persist independently of Portal connections. On
unexpected loss of the transport association, an ACTIVE Session
enters GRACE as specified in Section 4.8. Explicit detachment instead
places it in DETACHED. Its Windows and server-resident state are
preserved subject to those lifecycle rules. The compositor MAY blank
or lock the Session's outputs according to local policy while no Seat
is attached.
When a user resumes a session (from GRACE or DETACHED), the server:
1. Provisionally binds the authenticated association to the
Session for reconstruction.
2. Sends the current Window list, geometry, visibility, and
stacking order as defined in Section 5.2.2.1.
3. Commits attachment with MWS_SESSION_RESUME_COMPLETE as
specified in Section 5.2.2.1.
4. Re-establishes the base Seat and input state under Section 5.4
and reopens Audio streams under Section 5.6. Additional output
mappings and device enumeration require later extensions.
MWS supports independent Sessions and provides for multi-seat
attachment within a Session through extensions. A user may maintain
multiple concurrent Sessions, for example two independent desktop
environments. Additional Seats within one Session require an
applicable extension and remain subject to the single-association
model in Section 4.8.
MWS also supports explicit session detachment. A user may detach a
running session, preserving its Clients while leaving its windows,
compositor state, audio stream state, and GPU resources resident on
the server without any attached seats. The user may then initiate a
new session on the same portal device (for example, to perform
unrelated work) and later resume the detached session exactly where
it was left. This behaviour is directly analogous to detaching and
reattaching a GNU Screen or tmux session, but applied to a full
graphical desktop environment spanning one or more seats.
4.10. Local Transport Profile (Non-Normative)
Although MWS treats all portal devices as untrusted endpoints and
applies the same protocol semantics regardless of network location,
implementations may apply transport-layer optimisations when the
portal and server reside on the same physical host. These
optimisations must not alter protocol semantics, message ordering,
authentication requirements, or session isolation, and must remain
transparent to the portal.
Permitted implementation-level optimisations include:
* loopback-specific SCTP acceleration
* reduced cryptographic overhead
* shared-memory fast paths
* GPU-direct resource sharing where supported
These optimisations must not:
* grant additional privileges to local portals
* bypass certificate validation or user authentication
* modify the behaviour of control, input, audio, or rendering
streams
* introduce protocol features unavailable to remote portals
MWS remains a network-transparent window system. Local optimisations
exist solely to ensure that portal devices running on the same host
as the server achieve performance comparable to traditional
local-only systems without compromising the zero-trust security
model.
4.11. Security Model
All portals are treated as untrusted. Trust is established
exclusively through cryptographic identity and explicit authorisation
rather than network location. The server enforces strict isolation
between users, sessions, seats, and windows. In particular:
* at any point in time, a session is attached to at most one
transport association in the base protocol, and the server uses
the association on which a message is received as the
authoritative source of session context; portals cannot select
or override the session by supplying identifiers
* window identifiers are scoped to a session and cannot be
referenced by other sessions
* input events are scoped to a seat and session, and cannot target
windows outside that session
* portals cannot observe, enumerate, or reference resources
belonging to other sessions
* all portal-originated messages are validated before being
processed
Transport security is provided by DTLS 1.3 carried over SCTP using
the mapping defined by [I-D.6083BIS]. The mapping requires the
revised SCTP-AUTH extension it references, derived from [RFC4895],
including authentication of DATA and, when used, FORWARD-TSN chunks.
Implementations MUST follow the mapping's chunk-authentication and
key-management requirements; implementing [RFC4895] alone is not
sufficient. SCTP-AUTH does not encrypt MWS Messages. DTLS provides
confidentiality and integrity for MWS Messages. Deployments SHOULD
use DNS-Based Authentication of Named Entities (DANE) to bind the
server's certificate to DNSSEC-protected TLSA records, allowing
portals to verify that they are communicating with the correct
workstation even in the presence of compromised or mis-issued CA
certificates. Device identity is not part of the trust model; access
to user sessions is determined solely by user authentication and
server policy.
The DTLS profile is part of the base protocol. An external secure
tunnel MAY provide defence in depth but does not replace DTLS or
relax any MWS authentication requirement.
Deployments MAY additionally require portal authentication at the
transport layer (for example, mutual DTLS), but such device identity
is always subordinate to user-level authorisation.
Before sending user credentials or accepting Session state, the
Portal MUST authenticate the intended Workstation. The reference
identity is the DNS name or IP address selected by the user or
trusted local configuration before connection establishment. A name
supplied by the peer, an untrusted reverse-DNS result, or the
eventual destination address MUST NOT replace a configured DNS
identity.
For conventional PKI validation, the Portal MUST validate the
certificate chain against its configured trust anchors and verify the
reference identity according to [RFC9525]. A DNS identity is matched
against an appropriate subjectAltName DNS identifier; an IP literal
is matched against a subjectAltName IP address. The certificate
Common Name is not a substitute. A failed identity or trust check
MUST terminate establishment before application-layer authentication.
For DANE, the Portal MUST obtain DNSSEC-authenticated TLSA data for
the configured DNS reference identity and actual service port. In
this SCTP service profile, the TLSA owner name is formed by
prepending the decimal port number and transport labels, _port._sctp,
to that DNS reference identity. Certificate association and identity
checks follow the selected TLSA certificate usage under [RFC6698] and
[RFC7671]; conventional PKI name checks MUST NOT be substituted for
that usage-specific policy. An IP-literal connection requires an
independently configured DNS reference identity for DANE, or
conventional PKI IP-address verification.
When local policy requires DANE, missing usable authenticated TLSA
data, DNSSEC validation failure, or failure to match an authenticated
association MUST fail establishment. A failed DANE authentication
MUST NOT silently fall back to PKI. A deployment may permit PKI where
DANE is unavailable, but that choice must follow its configured
policy and still authenticate the same reference identity.
User authentication is performed at the application layer using the
mechanism-agnostic model defined in Section 5.2.1. The server
advertises supported mechanisms (for example, "PAM" and "FIDO2"), and
the portal selects one. This separation of device and user identity
ensures that device identity alone does not grant access to a user's
Session.
The Server validates all Portal-originated Messages, including Input
events. A Portal may not reference Windows, Sessions, or resources
outside its authenticated authority. Attempts to do so are rejected
with MWS_ERROR_SESSION (type=702, fatal=0). Invalid Messages are
handled according to Section 5.9. Recoverable errors permit the
Session to continue; handshake failures and malformed framing or
fragmentation are fatal.
The server does not trust the Portal as an authority over Session
state. The user nevertheless entrusts an active Portal with the
content it displays, the input it captures, and any authentication
material used there. If a portal disconnects unexpectedly, the
session persists only for the duration of the reconnection grace
period unless the user has explicitly detached. After this period,
the session is closed and applications terminate.
Unexpected loss of the transport association (network failure,
timeout, endpoint crash) is treated as a fatal transport error. The
Session MAY persist according to Section 4.8 and MAY be resumed from
another Portal subject to policy. MWS_SESSION_END instead announces
committed termination: subsequent association retirement is expected,
and that Session MUST NOT be resumed.
4.12. Clipboard Model
MWS clipboard exchange connects Applications in an authenticated
Session to applications on the Portal's desktop. It is independent
of the Client toolkit and of the workstation's console desktop.
Toolkit adapters translate their native clipboard operations into
MWS Messages; native desktop integration is a Portal responsibility.
A workstation need not have a local graphical desktop running.
The clipboard model is format-neutral. A clipboard item can offer
multiple representations, including plain text, rich text, images
and application-specific binary data. An offer describes available
formats; a receiver requests the representation it needs. Publishing
an offer MUST NOT require transmitting all of its representations.
Representation bytes MUST NOT be treated as UTF-8 merely because
they travel through MWS. Empty data and unavailable data are distinct
outcomes. Adapters MUST NOT silently reduce a multi-format item to
plain text, or advertise a representation they cannot supply.
Clipboard ownership and transfer authority are separate. An offer
does not authorise every Application to retrieve its contents. The
Server MUST validate the originating Application and its Session;
the Portal MUST apply native desktop access and focus policies.
Requests and replies MUST be associated with the authenticated
attachment, Seat, clipboard owner and offered item. They MUST NOT
be broadcast to other Sessions, including those of the same user.
A native clipboard shared by local applications does not itself
authorise an MWS endpoint to expose it to every connected Session.
Replacing ownership MUST invalidate the previous offer for new
requests. An outstanding request MUST either complete with the
representation it requested or fail; it MUST NOT silently receive
the replacement item's bytes. Implementations MUST retain storage
needed by accepted transfers until those transfers finish or are
cancelled, even if the originating Window or Application closes.
They MUST release that storage after its final use. A closed owner
cannot supply new data unless a clipboard manager has retained it
under the applicable desktop policy.
Transfers MUST have explicit completion, failure and cancellation
semantics. Large representations MUST be transferable incrementally
within negotiated Message limits, without requiring a single buffer
for the entire item. Receivers MUST validate lengths and arithmetic
before allocation or access. Backpressure and resource exhaustion
MUST produce defined outcomes without blocking the desktop event
loop indefinitely. Clipboard traffic MUST NOT starve Input or Audio.
On detach, association loss or Session replacement, endpoints MUST
cancel outstanding cross-boundary clipboard requests and revoke
attachment-specific offers. Session persistence does not preserve
authority to read a former Portal's clipboard. Resume requires fresh
offers and access checks; old replies MUST NOT be delivered into the
new attachment. Data already copied into a native clipboard manager
remains subject to that desktop's retention policy; MWS cannot
promise to revoke copies already delivered to other applications.
The ordinary copy-and-paste clipboard and selections such as X11
PRIMARY are distinct. Implementations MUST NOT silently merge them.
Unsupported native selection or format operations MUST have an
explicit unavailable or unsupported outcome. Native restrictions
remain applicable even when both endpoints are on the same machine.
Clipboard representation exchange does not transfer referenced
files. A pathname or file URL from the workstation MUST NOT be
interpreted as a Portal-local path merely because it was pasted,
and the same requirement applies in the opposite direction. An
adapter unable to preserve the meaning of such a reference MUST
decline the operation. Cross-machine file copy, cut and transfer
completion semantics are outside this clipboard profile. Receipt of
a clipboard representation MUST NOT by itself cause source-file
deletion or execution of a command embedded in that representation.
5. Protocol Specification
5.1. Message Framing
All MWS messages consist of a fixed-size header followed by an
optional payload. The header declares the exact payload length; a
message is therefore self-delimiting.
The header format is:
magic 4-octet unsigned integer
type 2-octet unsigned integer
reserved 2-octet unsigned integer
length 4-octet unsigned integer
postmark 8-octet unsigned integer
The common header is exactly 20 octets, without alignment padding.
magic MUST contain 0x4d657263, the ASCII octets "Merc". type is the
opcode registered in Appendix A. reserved MUST be zero. length is the
payload length in octets and does not include the header.
postmark records when the originating sender posts the Message for
delivery, in microseconds from its monotonic clock's arbitrary
origin. It is assigned before independent delivery queues, not at
eventual Transport transmission. Forwarding and queued copies of
the same Message MUST preserve it. A reply or another newly issued
Message receives its own postmark. All unsigned 64-bit values are
representable; equal postmarks do not establish an ordering.
Postmarks are comparable only within an established common clock
domain. They MUST NOT be compared with the receiver's clock or
assumed comparable across different hosts, reboots or replacement
origins. Connection or Session identity alone does not prove that
two forwarded Messages originated in the same clock domain.
The postmark is chronology, not identity or authority. It MUST NOT
relax framing, protocol-state, ownership or Session validation.
A postmark does not synchronise streams or require an
acknowledgement. Its value alone does not prove that a delayed
Message cannot still arrive: such an inference requires the
applicable conversation's posting and ordered-delivery guarantees.
Postmarks do not replace Render, Video or Audio media timestamps,
which govern presentation and playback rather than Message posting.
The 32-bit length field can represent payload lengths from zero to
4294967295 octets. This is the framing limit, not a requirement that
an endpoint accept a payload of every representable size. During
Session establishment, each endpoint declares the largest logical
payload it has resources to accept. A sender MUST NOT send a logical
Message whose declared payload length exceeds the peer's limit.
A receiver MUST validate the header against that limit before
allocating storage or processing the payload. Exceeding the
advertised limit is a resource error, not malformed framing.
Implementations MAY choose different receive limits according to
available memory and local policy.
The payload immediately follows the header. Implementations MUST
validate the magic value, type, and declared payload length before
processing the completed Message. An invalid header is a fatal
protocol error. The receiver MUST terminate the association and
SHOULD first send MWS_ERROR_PROTOCOL (type=701, fatal=1) when it can
safely construct and transmit that response within the peer's limits.
Integer and variable-length fields follow the wire-format conventions
in Section 2.6.
A Window identifier is not part of the common header because not
every MWS Message concerns a Window. Except for Error Messages, every
Message carrying a window_id MUST place it in the first four octets
of its payload. This conditional common prefix allows a recipient to
determine which Window a Message concerns without interpreting the
remainder of that Message's payload. Error Messages are the
exception: their diagnostic window_id follows the four-octet
error-correlation prefix specified in Section 5.9.
This routing-prefix rule applies to complete logical Messages. The
Transport-service envelopes MWS_MESSAGE_START, MWS_MESSAGE_APPEND,
and MWS_MESSAGE_ABANDON (types 800-802) do not expose a Window
routing field. Their payloads carry the fragmentation representation
defined in Section 5.1.1. Routing queries apply to the reconstructed
Message, not to a fragment or its outer envelope.
When a complete Portal-association MWS Message, including its
20-octet header, fits within the peer's max_user_message_size, it is
carried as the plaintext of one DTLS record in one SCTP user message.
In this document, max_user_message_size measures that plaintext,
including the outer MWS header but excluding DTLS and SCTP overhead.
Section 5.1.1 defines Transport fragmentation for a larger logical
Message.
MWS opcodes form a common Message vocabulary between Mercurius
endpoints. Not every MWS Message crosses the Portal association. A
"Portal-association" Message crosses that authenticated association.
A "client-channel" Message crosses the workstation-local boundary
between the Library and the Server. A Message MUST NOT cross a
boundary for which its definition does not permit it.
A Message may retain its opcode and payload while moving from one
scope to another. Some events are deliberately delivered across more
than one boundary so that each endpoint sees the Message appropriate
to its responsibility. These classifications describe semantic wire
senders and recipients, not internal server dispatch.
5.1.1. Transport Fragmentation
Fragmentation is a Transport concern. The protocol component sending
an ordinary MWS Message and its recipient operate only on the
complete logical Message. They do not inspect, originate, receive, or
handle the Transport Messages defined in this section.
If an ordinary complete MWS Message fits within the peer's declared
max_user_message_size, the Transport MUST send it unchanged. If it
does not fit, the Transport MUST send one MWS_MESSAGE_START. It MUST
then send as many MWS_MESSAGE_APPEND Messages as are required to
complete the logical Message, or send MWS_MESSAGE_ABANDON. Every
outer Message, including its 20-octet outer header, MUST fit within
the peer's max_user_message_size.
MWS_MESSAGE_START (type=800)
-- transport endpoint -> transport endpoint
The payload consists of the original 20-octet MWS header,
copied unchanged in network byte order, followed by zero or
more initial octets of the original payload.
The outer payload length MUST be at least 20. The retained
original header MUST be valid, MUST declare a payload no larger
than the receiver's max_payload_size, and MUST NOT contain type
800, 801, or 802.
MWS_MESSAGE_APPEND (type=801)
-- transport endpoint -> transport endpoint
The payload consists of one or more consecutive octets of the
original payload.
An empty MWS_MESSAGE_APPEND is a protocol error.
MWS_MESSAGE_ABANDON (type=802)
-- transport endpoint -> transport endpoint
Abandons the active fragmented logical Message on the same
association and SCTP stream. Its payload MUST be empty.
The receiver MUST maintain at most one active fragmented logical
Message for each association and SCTP stream pair. It validates and
retains the original raw header from MWS_MESSAGE_START, then appends
payload octets from successive MWS_MESSAGE_APPEND Messages on that
association and stream. It MUST deliver exactly one reconstructed
ordinary Message only after accumulating the payload length declared
in the retained original header.
While a fragmented Message is active on an association and stream:
* MWS_MESSAGE_APPEND is valid only for that active Message.
* MWS_MESSAGE_ABANDON discards the active Message and all of its
accumulated payload without delivering or acting upon it.
* A second MWS_MESSAGE_START on the same association and stream is
a protocol error.
* An ordinary MWS Message on the same association and stream is a
protocol error.
* Accumulating more payload octets than the retained original
header declares is a protocol error.
MWS_MESSAGE_START, MWS_MESSAGE_APPEND, and MWS_MESSAGE_ABANDON MUST
use reliable, ordered delivery. A fragmented sequence MUST NOT use
partial reliability or unordered delivery. Once a sender has emitted
MWS_MESSAGE_START, it MUST complete or abandon that logical Message
before sending another Message on the same association and stream. In
this revision, a fragmented MWS_RENDER_PRESENT MUST be completed, not
abandoned, so its generation can be included in cumulative Render
retirement. Unsent Render work may still be discarded before START.
MWS_MESSAGE_ABANDON without an active fragmented Message is a
protocol error. After an active Message has been abandoned, the next
ordinary Message or MWS_MESSAGE_START on that stream is valid.
Loss of an association discards every incomplete fragmented Message
for that association. An incomplete Message MUST NOT be delivered or
acted upon. A malformed sequence is a fatal protocol error and the
receiver MUST terminate the association after sending
MWS_ERROR_PROTOCOL when it is possible to do so safely.
A receiver MUST apply its declared payload and buffering limits
before allocating reassembly storage. Reassembly state and queued
fragment data MUST be bounded independently for each association so
that one peer cannot consume resources belonging to another.
Fragmentation is available only after the two-way MWS_SESSION_INFO
exchange. Before that exchange, endpoints MUST accept complete MWS
handshake Messages up to 16384 octets, including the MWS header.
Senders MUST fit them within that bound and any smaller negotiated
DTLS record limit. Credentials which cannot fit MUST be rejected;
handshake fragmentation is not defined. An endpoint's
max_user_message_size MUST be at least 88 octets, allowing the
unfragmented 68-octet MWS_SESSION_INFO payload and its header. This
also accommodates the two headers in MWS_MESSAGE_START.
5.2. Control Messages (Stream 0)
Control messages manage authentication, session establishment, window
lifecycle, and compositor state. All Portal-association control
Messages MUST be sent on SCTP stream 0.
The control channel is strictly ordered and defines the protocol
state machine for session creation, resumption, and teardown.
Other streams have independent delivery ordering. Scheduling and
processing priorities follow Section 4.7. This section groups related
protocol definitions; an explicit stream assignment within a Message
definition takes precedence over the section heading. In particular,
MWS_FOCUS_WINDOW uses Stream 2.
5.2.1. Initial Handshake (001-099)
The initial handshake establishes user identity and Session
parameters. DTLS 1.3 [RFC9147] over SCTP using [I-D.6083BIS],
optionally validated using DANE (Section 9.1), authenticates the
server and protects the transport. The application-layer handshake
authenticates the user and establishes a session.
The handshake and the resulting Session have different security
obligations:
1. The handshake must be cheap and fail fast so that an
unauthenticated peer cannot consume disproportionate server
resources.
2. The Session must remain secure against a capable, persistent
attacker after authentication has succeeded.
MWS_QUERY is deliberately an empty Message under the first of these
rules. Receiving it MUST NOT cause the server to parse peer-supplied
negotiation data or allocate Session resources. Authentication
failures, malformed handshake Messages, and unsupported mechanisms
MUST be rejected without creating a Session.
User authentication is mechanism-agnostic. The server advertises one
or more supported authentication mechanisms, and the portal selects
one. This allows deployments to integrate PAM, WebAuthn, FIDO2,
Kerberos, OAuth2, or future mechanisms without modifying the
protocol.
The handshake proceeds as follows on SCTP stream 0:
1. MWS_QUERY (type=001) -- Portal -> Server
Requests the server's authentication challenge. MWS_QUERY has
no payload. A non-zero payload length is a protocol error.
2. MWS_AUTH_CHALLENGE (type=002) -- Server -> Portal
Advertises the available authentication mechanisms. The payload
contains a list of mechanism identifiers followed by a fresh
per-association authentication nonce.
Payload format:
mechanism_count 1-octet unsigned integer
repeated mechanism_count times:
name_len 1-octet unsigned integer
name name_len octets
nonce_len 1-octet unsigned integer
nonce nonce_len octets
Mechanism names are UTF-8 strings and are not NUL-terminated.
name_len MUST be between 1 and 64 octets, as specified in
Appendix B. mechanism_count MAY be zero, in which case the
portal MUST abort the handshake. nonce_len MUST be 32. The
nonce MUST be generated using a cryptographically secure random
number generator and MUST be unique to the transport
association. Mechanism-specific use of the nonce is defined by
that mechanism. SSHKEY binds its proof to the association
through tls-exporter, as specified in Appendix B.1. PAM
transmits a password inside the authenticated encrypted
channel; it is not a nonce-based proof.
3. MWS_AUTH_RESPONSE (type=003) -- Portal -> Server
Selects an authentication mechanism and provides
mechanism-specific credentials.
Payload format:
mech_name_len 1-octet unsigned integer
mechanism mech_name_len octets
credential_len 2-octet unsigned integer
credential credential_len octets
mechanism MUST exactly match one of the names advertised in
MWS_AUTH_CHALLENGE. If the mechanism is unknown or the payload
length is inconsistent, the server MUST respond with
MWS_ERROR_PROTOCOL (type=701, fatal=1).
A cryptographic mechanism that proves possession of a reusable
credential MUST bind that proof to the current DTLS
association. Such a proof MUST NOT consist only of data
supplied by the Portal or of the reusable MWS_AUTH_CHALLENGE
payload. The SSHKEY mechanism uses the tls-exporter channel
binding defined by [RFC9266], as specified in Appendix B.1.
4. Bootstrap Session establishment
The server creates a bootstrap Session and completes the
two-way MWS_SESSION_INFO exchange. This Session provides the
environment in which a Session selector can communicate with
the Portal.
5. MWS_SESSION_RESUME_OFFER (type=100) -- Server -> Portal
Lists the authenticated user's resumable Sessions. The server
sends this Message even when the list is empty. Its payload is
defined in Section 5.2.2.
6. Session selection -- Portal -> Server
The Portal selects with MWS_SESSION_NEW_REQUEST (type=104) or
MWS_SESSION_RESUME_REQUEST (type=101). MWS_SESSION_NEW_REQUEST
continues the bootstrap Session. MWS_SESSION_RESUME_REQUEST
replaces it with the selected Session.
7. Resumed Session establishment
When an existing Session is selected, the peers perform a new
two-way MWS_SESSION_INFO exchange for that Session before its
state is reconstructed.
MWS_SESSION_INFO (type=004) -- Server <-> Portal
For each exchange, the Server MUST send this Message first. The
Portal MUST reply with exactly one MWS_SESSION_INFO carrying
the same Session identifier and its own receive limits. The
same exchange establishes the bootstrap Session and a resumed
Session.
Payload format:
session_id 4-octet unsigned integer
version_major 4-octet unsigned integer
version_minor 4-octet unsigned integer
version_revision 4-octet unsigned integer
max_payload_size 4-octet unsigned integer
max_user_message_size 4-octet unsigned integer
receive_mtu 4-octet unsigned integer
render_limit_bytes 8-octet unsigned integer
render_limit_presents 4-octet unsigned integer
render_rate_hint_kbps 4-octet unsigned integer
playback_min_rate_hz 4-octet unsigned integer
playback_max_rate_hz 4-octet unsigned integer
playback_channels_formats 4-octet unsigned integer
capture_min_rate_hz 4-octet unsigned integer
capture_max_rate_hz 4-octet unsigned integer
capture_channels_formats 4-octet unsigned integer
All fields are in network byte order. session_id is assigned by
the Server and MUST be non-zero. max_payload_size is the
largest payload of a complete logical MWS Message the sending
endpoint will accept. It MUST be at least 68 and MUST NOT
exceed 4294967295.
max_user_message_size includes the complete outer MWS header
and payload carried in one SCTP user message. It MUST be at
least 88 octets, sufficient for an unfragmented
MWS_SESSION_INFO. The Session-info payload length MUST be
exactly 68 octets.
The three version fields report the sending endpoint's
implementation version. Each implementation assigns its own
values; this specification assigns no implementation-version
tuple. These fields do not negotiate protocol capabilities.
Different implementations can conform to this revision while
reporting different versions. A deployment MAY apply an
implementation-specific compatibility policy to known versions,
including requiring matching versions of the same
implementation. Numeric equality alone does not establish
protocol conformance.
A deployment MUST establish that both endpoints support this
protocol revision before ordinary Session traffic begins. This
revision defines no automatic protocol-version negotiation or
downgrade. An endpoint MUST terminate establishment if it
cannot establish protocol compatibility or if Session Info is
malformed. The Server MUST send fatal MWS_ERROR_PROTOCOL in
reply to invalid Portal Session Info. Neither endpoint may
proceed with ordinary Session traffic before accepting the
peer's Session Info. The version fields remain at offsets 4, 8
and 12 immediately after session_id.
receive_mtu is the largest SCTP packet, in the path-MTU units
defined by [RFC6458], that the endpoint can receive without IP
fragmentation. A value of zero means unknown. An endpoint uses
the smaller of its own SCTP path estimate and the peer's
non-zero receive_mtu for that association. This field does not
limit the size of a logical MWS Message or SCTP user message.
In the Server-to-Portal form, render_limit_bytes,
render_limit_presents, render_rate_hint_kbps and the six Audio
fields MUST be zero. In the Portal-to-Server form,
render_limit_bytes and render_limit_presents declare the
maximum Render work the Portal can safely have outstanding on
this association while retaining sufficient capacity for
Control, status and recovery. Both limits MUST be non-zero. The
Server MUST NOT exceed either limit.
render_rate_hint_kbps is the Portal's advisory initial Render
rate in kilobits per second, or zero when unknown. It MAY be
derived from the interface selected by the route to the Server.
It is neither an end-to-end capacity guarantee nor an admission
limit. The Server MAY use it to choose an initial pace but MUST
remain within the declared Render flight and SHOULD refine
pacing from MWS_SESSION_STATUS. When the Server also knows the
advertised rate of its route-selected interface, it MUST NOT
pace Render above the lesser non-zero endpoint rate. Subsequent
status may reduce the working rate below that ceiling but does
not increase the endpoint link hint.
The playback fields declare the inclusive PCM sample-rate
envelope, maximum interleaved channel count and sample formats
which the Portal can play. The capture fields declare the
corresponding envelope for a Portal-attached capture device. In
each channels_formats field, the high 16 bits contain the
channel count and the low 16 bits contain the format set. Bit
zero advertises L16, bit one L24 and bit two F32. An
implementation MUST omit a format unsupported in that
direction. All three fields for an unsupported direction MUST
be zero. For a supported direction, the rate bounds, channel
count, and format set MUST be non-zero, the maximum rate MUST
be at least the minimum rate, and undefined format bits MUST be
zero.
An endpoint MUST NOT send a logical payload larger than the peer's
declared max_payload_size or a complete outer MWS Message larger than
the peer's declared max_user_message_size. The advertised value MUST
also conform to the DTLS-over-SCTP profile defined by [I-D.6083BIS].
A max_user_message_size smaller than 88 is a protocol error and
terminates Session establishment.
In the absence of a negotiated DTLS extension increasing the
plaintext record limit, max_user_message_size MUST NOT exceed 2^14
octets. Transport fragmentation therefore permits a logical MWS
payload to remain larger than one DTLS record without changing the
ordinary Message seen by its sender or recipient.
Other presentation, input, and subsystem capabilities are negotiated
by their respective protocol Messages after this base Session
exchange. The Render-flight fields above are the explicit admission
envelope, not implicit implementation defaults.
For a new Session, establishment completes after the server has
received and accepted the Portal's bootstrap MWS_SESSION_INFO. The
bootstrap Session is then ACTIVE and can run the Session selector,
including its Window, Input, Render, and Audio traffic, while the
selection offer remains outstanding. MWS_SESSION_NEW_REQUEST ends
selection without repeating establishment. For a resumed Session, the
server then sends MWS_SESSION_RESUME_COMPLETE as defined in
Section 5.2.2; establishment completes when that Message is sent.
Ordinary traffic for a resumed Session MUST NOT be processed before
that boundary. Before bootstrap establishment, either endpoint MUST
reject non-handshake traffic. From the Server's target Session-info
Message through resumption completion, only that exchange, the
reconstruction sequence, and fatal error handling are permitted on
Stream 0. Section 5.2.2.1 defines how in-flight bootstrap traffic is
drained before the association changes Session.
5.2.1.1. Session Identifier Semantics
The session identifier returned in MWS_SESSION_INFO is assigned
solely by the server. Portals MUST treat this value as opaque and
MUST NOT attempt to select, predict, or construct session
identifiers. All portal-originated messages that include a session_id
field convey no routing authority. The Server validates ordinary
traffic against the attached Session and resumption requests against
the outstanding offer, as defined in Section 4.7.1.
A portal MUST NOT assume that a session identifier remains valid
across reconnects unless the server has explicitly offered the
session for resumption. An identifier assigned to a live, detached,
or grace-period Session MUST NOT be reused. A server that reuses an
identifier after its former Session has terminated MUST ensure that
no association, resume offer, or retained protocol state can still
refer to the former Session. Possession of a session identifier alone
never conveys authority.
MWS_SESSION_INFO does not carry a resume token. Resumable Sessions
are advertised explicitly with MWS_SESSION_RESUME_OFFER after fresh
authentication.
5.2.2. Session Management (100-199)
Session resume allows a portal to reattach to an existing session
previously detached by the user or preserved during the reconnection
grace period.
MWS_SESSION_RESUME_OFFER (type=100) -- Server -> Portal
After bootstrap establishment, lists the Sessions that the
already authenticated user may resume.
Payload format:
session_count 2-octet unsigned integer
repeated session_count times:
session_id 4-octet unsigned integer
All fields are in network byte order. session_count MAY be
zero. Every listed session_id MUST be non-zero and MUST appear
at most once. An offer authorises a resumption request only on
the association on which it was sent and only until Session
selection succeeds or the association ends.
MWS_SESSION_RESUME_REQUEST (type=101) -- Portal -> Server
Requests resumption of one Session from the preceding offer.
Payload format:
session_id 4-octet unsigned integer
session_id is in network byte order and MUST identify a Session
in the preceding offer.
MWS_SESSION_RESUME_COMPLETE (type=102) -- Server -> Portal
Confirms that Session resumption and state reconstruction are
complete. This Message has no payload. A non-zero payload
length is a protocol error.
MWS_SESSION_DETACH (type=103) -- Portal -> Server
Requests deliberate detachment of the current Session. This
Message has no payload; the Session is identified by the
authenticated association on which the Message arrives; the
common MWS header contains no Session identifier. A non-zero
payload length is a protocol error.
On accepting the request, the server MUST preserve the Session
and its Clients for later resumption subject to local policy,
and detach the Portal. The Server MAY continue executing the
Clients or MAY suspend them while detached. The detached
association MUST NOT retain authority to send Session traffic.
MWS_SESSION_DETACH does not terminate the Session.
MWS_SESSION_NEW_REQUEST (type=104) -- Portal -> Server
Selects the existing bootstrap Session as the user's new
Session. This Message has no payload. A non-zero payload length
is a protocol error.
MWS_SESSION_STATE_BEGIN (type=105) -- Server -> Portal
(Portal association)
Begins reconstruction of a resumed Session. The Portal MUST
discard any presentation state retained for the Session before
accepting the reconstruction sequence in Section 5.2.2.1.
Payload format:
window_count 4-octet unsigned integer
window_count is in network byte order and declares the exact
number of Windows in that sequence. Each is introduced by one
MWS_WINDOW_CREATED and followed by the metadata Messages
specified in Section 5.2.2.1. window_count MAY be zero. The
payload length MUST be exactly four octets.
MWS_SESSION_STATUS (type=106) -- Portal -> Server
(Portal association)
Reports cumulative Session presentation delivery and retirement
progress. Render and Video share one presentation sequence and
admission envelope.
This unsolicited control-plane Message is inspired by Saratoga
STATUS [SARATOGA]: rendering proceeds within a bounded
unconfirmed horizon rather than requiring an acknowledgement
for every presentation.
The payload is:
status_epoch 8-octet unsigned integer
retired_sequence 8-octet unsigned integer
received_sequence 8-octet unsigned integer
retained_bytes 8-octet unsigned integer
render_limit_bytes 8-octet unsigned integer
retained_presentations 8-octet unsigned integer
render_limit_presentations 8-octet unsigned integer
render_state 4-octet unsigned integer
reserved 4-octet unsigned integer
status_epoch starts at 1 and increases for each snapshot on the
current Session attachment. received_sequence is the highest
Session presentation sequence through which every complete
logical Message has arrived and been validated for admission.
retired_sequence is the highest sequence through which no work
still consumes Portal capacity. Both start at zero. The Server
assigns one contiguous sequence, starting at one, across
transmitted MWS_RENDER_PRESENT and MWS_VIDEO_DATA Messages.
Arrival and retirement may occur out of order across their
independent streams; neither frontier may skip missing work. A
presentation is retired after it has been presented,
deliberately superseded, or made stale by newer current state.
It does not acknowledge every intervening frame.
retained_bytes and retained_presentations report work currently
owned by the Portal, including Render and Video.
render_limit_bytes and render_limit_presentations are absolute
safe ceilings offered by the Portal. The Server MUST NOT admit
presentation work which would exceed either ceiling. A later
snapshot may tighten a ceiling while already admitted work
drains.
render_state is 0 for healthy, 1 for constrained, 2 for
drain-only and 3 when the Portal cannot make presentation
progress. reserved MUST be zero. Every integer is in network
byte order. retired_sequence MUST NOT exceed received_sequence,
which MUST NOT exceed a sequence sent on the current
association. Snapshots whose status_epoch is not newer than the
last accepted epoch MUST be ignored. A newer snapshot MUST NOT
reduce either frontier. Epochs and presentation sequences MUST
NOT wrap; a new association is required before exhaustion. All
reset on Session replacement.
The Server MUST retain enough sequence-to-message-length state
to convert the cumulative report into released byte credit. It
SHOULD use retirement progress and retained work to learn a
conservative healthy rate, then pace later presentation
admission within the hard safe ceilings in the latest accepted
status, initially established by MWS_SESSION_INFO. The two
frontiers and retained work distinguish delivery from Portal
processing progress; the Server SHOULD combine them with its
Transport observations rather than treating Portal processing
pressure as path congestion. Render remains the preferred
presentation; Video is a fallback when the path cannot sustain
the required Render delivery. Status is not a prerequisite for
the first frame. The Portal MUST send snapshots at
approximately 250 ms intervals, independently of individual
presentations and native GPU processing. It MUST NOT send a
snapshot in response to every Render or Video picture. The
Portal MUST eventually send a status snapshot when retirement
releases credit, even if no further presentation work arrives;
otherwise a sender at its limit could stall forever. The fixed
payload length is 64 octets.
MWS_SESSION_STATUS MUST be sent reliably and in order on Stream
0 and MUST be prioritised over traffic on every non-control
stream. A status report MUST NOT wait for processing on any
non-control stream. Byte credit counts the complete logical
Message (20-octet MWS header plus payload), excluding DTLS/SCTP
and fragmentation overhead. Each MWS_RENDER_PRESENT or
MWS_VIDEO_DATA consumes one presentation credit. Credit is
reserved before transmission and released only by cumulative
retirement. Decoded images and reassembly also require locally
bounded storage; wire byte credit is not a decoded-memory
limit.
MWS_SESSION_CLOSE_REQUEST (type=107) -- Portal -> Server
Requests termination of the Session identified by the
authenticated Portal association, including all its
Applications. This Message has no payload and cannot select a
different Session. The Server MUST terminate the attached
Session under Section 4.8 without entering GRACE or DETACHED or
waiting for the reconnection grace period. A DETACHED Session
has no attached association and cannot be targeted directly by
this Message; an authorised Portal must resume it before
requesting its closure. The request remains valid after the
desktop Client or its Windows have exited.
MWS_SESSION_END (type=108) -- Server -> Portal
Announces that the Server has committed termination of the
Session attached to this authenticated association. This
Message has no payload and MUST be sent reliably and in order
on Control Stream 0. It is valid only for an established,
attached Session. A Portal MUST NOT send this Message, and
receipt with a non-empty payload is a protocol error.
The Server MUST close admission of further Session work before
appending MWS_SESSION_END as the final Session Control Message,
after all previously admitted Control Messages. It MUST drain
that Message before orderly association retirement. Receipt
marks nonresumable Session termination, not completed resource
reclamation, Application exit or native presentation on other
streams. The Portal MAY discard remaining presentation work
and finish its local Session normally upon receipt.
MWS_SESSION_END is independent of MWS_EXEC_RESULT. It MUST NOT
fabricate or replace an Application result, nor turn an already
reported failure into success. A Portal MUST NOT infer a
successful terminal transition from association closure alone.
Server-side application launch allows a Portal to request that the
Server start a Client under the authenticated Session. For example,
radialblur is the Client when requested and run this way.
MWS_EXEC_REQUEST (type=110) -- Portal -> Server
Requests execution of a program under the current Session.
Payload format:
request_id 4-octet unsigned integer
exec_flags 2-octet unsigned integer
argument_count 2-octet unsigned integer
arguments argument_count argument fields
Each argument field has this format:
argument_len 2-octet unsigned integer
argument argument_len octets
request_id MUST be non-zero and identifies this request within
the Session. Each response Message caused by this request MUST
carry the same request_id. A Portal MUST NOT reuse a request_id
while the corresponding request remains outstanding. The Server
MUST reject a duplicate outstanding request_id. request_id is
correlation data only and conveys no authority over a Client or
any other Session resource. Each argument is a UTF-8 string
without a terminating NUL and MUST NOT contain U+0000. The
following exec_flags values are defined:
0x0001 RETURN_STDOUT
0x0002 RETURN_STDERR
RETURN_STDOUT requests that the Server return the Client's
standard-output stream to the Portal. RETURN_STDERR requests
the corresponding standard-error stream. The values are
protocol flags rather than file-descriptor numbers; their
correspondence with POSIX descriptors 1 and 2 is mnemonic.
Flags may be combined. Undefined bits are reserved and MUST be
zero.
When argument_count is non-zero, the first argument names the
program and MUST NOT be empty. Subsequent arguments MAY be
empty. An argument_count of zero requests the Server's default
Session program; the reference implementation uses mwsdm. This
distinguishes an explicit default-program request from the
absence of a request. argument_count MUST NOT exceed 65535;
argument_len MUST NOT exceed 65535 octets; and the complete
payload MUST NOT exceed 65535 octets.
Argument boundaries are significant. The Server MUST pass the
decoded arguments directly to the requested program without
joining them into a command line or invoking a command-language
interpreter. This argument-vector model follows the exec family
specified by POSIX.1-2024 [POSIX-EXEC]. The Server resolves and
launches the named program according to local policy. It MUST
reject a request which exceeds the host's argument and
environment limit. Environment changes are not defined by this
version.
MWS_EXEC_RESULT (type=111) -- Server -> Portal
Reports that the program requested by MWS_EXEC_REQUEST has
terminated or could not be launched.
Payload format:
request_id 4-octet unsigned integer
kind 1-octet unsigned integer
flags 1-octet unsigned integer
reserved 2-octet unsigned integer
code 4-octet unsigned integer
diagnostic_len 1-octet unsigned integer
diagnostic diagnostic_len octets
request_id MUST identify the corresponding MWS_EXEC_REQUEST.
Multi-octet integers are in network byte order. diagnostic is
an opaque variable-length field as defined in Section 2.6:
diagnostic_len gives its exact length and the octets follow
immediately, without a terminator. reserved MUST be zero. kind
is 0 when the program exited normally, 1 when it was terminated
by a signal, and 2 when it could not be launched. code is
respectively the exit status or signal number. It MUST be zero
when kind is 2. A Portal MUST NOT infer a signal from an exit
status.
diagnostic is a bounded final sequence of output retained for
an unsuccessful request when neither live output stream was
requested. It MUST NOT exceed 255 octets and MUST be empty
after successful execution or when either RETURN_STDOUT or
RETURN_STDERR was requested. Bit 0 of flags indicates that
further diagnostic output was discarded; all other flag bits
MUST be zero. The payload length MUST equal thirteen plus
diagnostic_len. Servers MUST NOT include internal path, policy,
loader, or other implementation details merely to explain a
rejected launch.
MWS_EXEC_STDOUT (type=112) -- Server -> Portal
MWS_EXEC_STDERR (type=113) -- Server -> Portal
Carries bytes read from the requested Client's standard-output
or standard-error stream when the corresponding
MWS_EXEC_REQUEST flag was set.
Payload format:
request_id 4-octet unsigned integer
output remaining payload octets
request_id MUST identify the corresponding MWS_EXEC_REQUEST.
output is an opaque sequence of one or more octets; it is not
necessarily UTF-8 and has no terminator. output MUST NOT exceed
4096 octets. Empty output Messages MUST NOT be sent.
The Server MUST send output promptly as it reads it rather than
retaining it until Client termination. Byte order is preserved
independently within each output stream. The order between
MWS_EXEC_STDOUT and MWS_EXEC_STDERR is the order in which the
Server reads their chunks; no ordering of writes across the two
Client streams is implied.
These Messages use the reliable ordered Control stream. The
Server MUST send every final output Message before the
corresponding MWS_EXEC_RESULT. Output not requested by
exec_flags MUST NOT be sent. An output Message MUST NOT contain
bytes from another Client, request, or Session. Output pending
when the association is lost MAY be discarded.
MWS_CONFIG_QUERY (type=120) -- Client/Server -> Portal
Requests one desktop configuration value on demand. The Message
crosses the Client Channel from Library to Server and the
Portal association from Server to Portal.
Payload format:
application_id 4-octet unsigned integer
request_id 4-octet unsigned integer
namespace_len 2-octet unsigned integer
key_len 2-octet unsigned integer
namespace namespace_len octets
key key_len octets
A Client MUST set application_id to zero. The Server MUST
replace it with the non-zero Session-scoped identifier of the
sending Application before forwarding the query. request_id
MUST be non-zero and outstanding identifiers MUST be unique
within that Application. The Server MAY originate a Session
configuration query with application_id zero. This value then
addresses the Session itself, not any Application; request_id
MUST be unique among that Session's outstanding queries.
namespace and key are non-empty UTF-8
strings without terminators and MUST NOT exceed 255 octets
each. Names use the freedesktop.org Settings vocabulary
[XDG-SETTINGS] where applicable. A Portal MUST expose only
supported configuration values; this Message is not a general
D-Bus or native desktop API proxy.
XDG Desktop Portal is a local desktop service, distinct from an
MWS Portal. An MWS Portal can consult its Settings interface to
obtain supported preferences. MWS does not require D-Bus, an
XDG service, or a particular desktop environment at either
endpoint. Desktop-specific extensions are not universal XDG
settings.
The org.mercurius.display namespace defines width and height
as UINT32 pixel dimensions of the Portal's primary output at
Session startup. These Application queries do not enumerate
multiple outputs or subscribe to subsequent display changes.
A Portal unable to discover a dimension returns UNAVAILABLE.
MWS_CONFIG_RESULT (type=121) -- Portal -> Client
Reports the outcome of MWS_CONFIG_QUERY through the Server.
Payload format:
application_id 4-octet unsigned integer
request_id 4-octet unsigned integer
status 2-octet unsigned integer
value_type 2-octet unsigned integer
value_len 4-octet unsigned integer
value value_len octets
application_id and request_id MUST equal the values in the
query. The Server MUST deliver the result only to that
Application, or consume it as Session configuration when
application_id is zero. Unsolicited results MUST NOT change
Session configuration. status is 0 for success, 1 not found, 2
unavailable, 3 not supported, or 4 invalid. An unsuccessful
result MUST use value_type 0 and an empty value. Successful
value types are 1, an unsigned 32-bit integer; 2, UTF-8 text;
and 3, three unsigned 16-bit red, green and blue components.
All integers use network byte order. value_len MUST NOT exceed
4096 octets and MUST exactly match the remaining payload.
The namespace "org.mercurius.session" and key
"regional-settings" request a startup snapshot of the Portal
user's regional preferences. A successful result is UTF-8 text
containing one or more name=value lines, each terminated by LF.
Names MUST be unique and drawn only from TZ, LANG, LANGUAGE,
LC_ALL, LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY,
LC_MESSAGES, LC_PAPER, LC_NAME, LC_ADDRESS, LC_TELEPHONE,
LC_MEASUREMENT and LC_IDENTIFICATION. Values MUST be non-empty,
at most 255 octets, and contain neither CR nor LF. This is a
fixed preference vocabulary, not arbitrary environment
forwarding.
TZ denotes an IANA timezone name, not an offset or a pathname.
Receivers MUST validate it against trusted local timezone data
without opening a pathname selected by the peer. Other fields
express locale and translation-language preferences; receivers
MUST validate syntax and local support before applying them.
These preferences convey no authority and MUST NOT change the
Server's administrative environment or protocol timing.
A Session MAY adopt this snapshot before starting its services
and Applications. All Applications in that Session then inherit
the same startup preferences. Missing or unsupported
preferences MUST have a defined local fallback. Implementations
MUST NOT claim that changing an execution environment updates
existing processes. Preference changes on Session resume are
outside this startup profile. Named timezones retain their
normal seasonal transitions according to the workstation's
timezone database.
These Messages use the reliable ordered Control stream. Desktop
configuration MUST NOT be included speculatively in
MWS_SESSION_INFO; a Client or Server requests only values it
needs.
MWS_CONFIG_WATCH (type=122) -- Client -> Portal
Subscribes to one desktop configuration value through the
Server. Its payload is identical to MWS_CONFIG_QUERY, with
request_id identifying the subscription rather than a query.
A Client MUST set application_id to zero; the Server MUST stamp
its authoritative non-zero Application identifier. A network
WATCH MUST NOT use application_id zero.
Subscription identifiers MUST be non-zero, strictly increasing
within each Application and Portal attachment, and MUST NOT be
reused after cancellation or termination. They form a separate
identifier space from on-demand query identifiers. Exhaustion
MUST NOT wrap an identifier into a previously used value.
The Portal MUST establish observation before reading the
initial value, and serialise that snapshot with subsequent
changes. It MUST send an initial MWS_CONFIG_UPDATE. A
successful initial snapshot establishes the subscription.
Subsequent updates carry the current value when it changes;
they MUST NOT precede the initial snapshot. An unsuccessful
initial or later update ends the subscription and MUST be the
final update for that route. Unsupported settings MUST report
NOT_SUPPORTED rather than silently establishing a subscription
which never updates.
The initial supported watch profile is namespace
"org.freedesktop.appearance", key "color-scheme". Its
successful value is UINT32: 0 means no preference, 1 prefers
dark and 2 prefers light. Subscription grants no native desktop
authority and MUST NOT expose arbitrary D-Bus or environment
state.
MWS_CONFIG_UNWATCH (type=123) -- Client/Server -> Portal
Cancels one subscription through the Server.
Payload format:
application_id 4-octet unsigned integer
request_id 4-octet unsigned integer
Address stamping and identifier rules are those of WATCH. The
Server MAY originate cancellation when an Application exits or
its route is retired, using that Application's authoritative
non-zero identifier and the existing subscription identifier.
This does not create a Server-owned subscription.
Cancellation is idempotent: retiring an already absent route
succeeds without a reply. The Client and Server MUST retire
their route before forwarding cancellation. The Portal MUST
stop producing updates after consuming cancellation. Updates
already in flight MUST be discarded by retired receivers.
MWS_CONFIG_UPDATE (type=124) -- Portal -> Client
Supplies the initial subscription snapshot or a later change.
Its payload and status/value encoding are identical to
MWS_CONFIG_RESULT. application_id MUST be non-zero and both
identifiers MUST match a live WATCH on the same attachment.
The Server MUST deliver an update only to that Application.
Unsolicited or retired updates MUST be discarded without
changing Session or Application configuration. A non-OK status
terminates the route, including an initially refused WATCH.
WATCH, UNWATCH and UPDATE use the reliable ordered Control
stream. Application exit, Portal loss and Session destruction
retire their subscriptions. Subscriptions do not survive Portal
reattachment; an Application needing updates MUST subscribe
afresh. No route or native observation may outlive its owning
Application or attachment. These Messages do not alter the
on-demand QUERY/RESULT exchange or require speculative settings
in MWS_SESSION_INFO.
5.2.2.1. Resume Semantics
A session becomes resumable when the user has explicitly detached it
or when the transport association (for example, an SCTP association)
has been lost and the session has entered the reconnection grace
period defined in Section 4.8. The server MUST NOT offer resumption
for sessions that have been terminated or reclaimed by policy.
After successful user authentication, the server MUST send exactly
one MWS_SESSION_RESUME_OFFER (type=100), after the bootstrap
MWS_SESSION_INFO exchange. An empty offer tells the Portal that no
resumable Session is available while preserving the same
state-machine ordering in both cases. The Portal MUST answer with
MWS_SESSION_NEW_REQUEST or MWS_SESSION_RESUME_REQUEST. Only one
selection request may be outstanding. A rejected resume request MAY
be followed by another selection request against the same offer.
On MWS_SESSION_NEW_REQUEST, the bootstrap Session continues as the
user's selected Session. It is not destroyed and recreated.
To resume a session, the portal sends MWS_SESSION_RESUME_REQUEST
(type=101) specifying the session identifier. The server MUST
validate that the requested session:
* belongs to the authenticated user
* is currently resumable
* is not attached to or reserved for another Portal
Before sending MWS_SESSION_RESUME_REQUEST, the Portal MUST stop
originating bootstrap Session traffic and wait for SCTP
acknowledgement of all previously transmitted bootstrap Messages on
every stream. The Server continues processing bootstrap traffic until
that request arrives. If the request is rejected, bootstrap traffic
may continue.
If validation succeeds, the Server reserves the target Session and
stops originating bootstrap traffic. It MUST finish sending queued
bootstrap Messages, or discard unsent work, and wait for SCTP
acknowledgement of transmitted bootstrap Messages before sending the
target's MWS_SESSION_INFO. The Portal drains received bootstrap
Messages before replying with the target's MWS_SESSION_INFO. Both
endpoints MUST finish or discard queued bootstrap processing before
changing Session context. This transition barrier prevents traffic
without an explicit session_id from being interpreted in the resumed
Session. Implementations MUST NOT infer a cross-stream barrier merely
from Stream 0 message ordering.
After accepting the Portal's MWS_SESSION_INFO, the Server atomically
replaces and destroys the bootstrap Session and cancels the target's
reconnection grace timer. It takes a consistent snapshot of the
target's Windows. This provisional binding authorises reconstruction
only. The following logical Messages MUST be sent consecutively on
Stream 0:
1. MWS_SESSION_STATE_BEGIN with the snapshot's Window count.
2. Exactly that many MWS_WINDOW_CREATED Messages, in bottom-to-top
stacking order. Each carries the current Window identifier,
extent, and title, with request_id zero to mark reconstruction.
The Portal creates provisional, initially unmapped Windows.
3. For each Window in the same order: MWS_CONFIGURE_WINDOW,
MWS_WINDOW_STATE, MWS_WINDOW_RELATION, MWS_WINDOW_ICON,
MWS_WINDOW_IDENTITY, and MWS_WINDOW_CURSOR; then, for a Window
with delegated server decoration, MWS_DECORATION_STATE followed
by MWS_DECORATION_FRAME if a current retained frame exists;
then exactly one of MWS_MAP_WINDOW or MWS_UNMAP_WINDOW. These
carry the current geometry, constraints, relationship, icon,
cursor, decoration state and visibility. Default state is sent
explicitly, including unshaded decoration state. Decoration
replay follows Section 5.2.3.2. All referenced parent Windows
have already been introduced in step 2.
4. MWS_SESSION_RESUME_COMPLETE.
MWS_SESSION_RESUME_COMPLETE is the commit boundary. The Portal MUST
NOT expose partial reconstruction or originate ordinary
resumed-Session traffic before receiving it. The Server attaches the
Portal and marks the Session ACTIVE when sending it. Live changes
made after the snapshot MUST follow that boundary. A fatal error may
abort reconstruction at any point; no other unrelated logical Message
may interrupt the sequence. Transport fragmentation wrappers do not
count as intervening Messages.
The Portal MUST reject a wrong count, a zero or duplicate Window
identifier, a wrong Message order, invalid metadata, or a reference
to a Window outside the snapshot. These are fatal protocol errors. On
association loss before completion, partial Portal state is
discarded, the reservation is released, and the target Session
follows Section 4.8; a target not yet rebound retains its previous
state and grace deadline.
Render and Audio Messages can arrive before Stream 0's commit
boundary. The Portal MUST retain such data within its advertised
limits until reconstruction completes, or terminate on resource
exhaustion. After reconstruction, the Server MUST establish complete
pixel content before sending partial updates for each Window. The
base Seat is re-established under Section 5.4; Audio streams are
reopened under Section 5.6. Focus is re-established through
MWS_FOCUS_WINDOW: the Portal reports fresh native focus transitions
and the Server determines the authoritative Session focus as
specified in Section 5.2.3. Additional Seats, device enumeration, and
output mappings require later extensions.
If validation fails, the server MUST reject the request with
MWS_ERROR_SESSION (type=702, fatal=0), MUST NOT alter the requested
Session, and MUST NOT reveal the existence or attributes of Sessions
belonging to other users. The Portal remains in Session selection
state and MAY request a new Session or another Session from the same
offer.
At most one Portal may be attached to a Session at a time. The Server
MUST reject competing requests once the target is reserved or ACTIVE.
Forced takeover of an active Session is outside this base protocol.
5.2.2.2. Clipboard Exchange
Clipboard offers, requests and cancellation use the reliable ordered
Control stream. Every MWS_CLIPBOARD_RESULT uses the reliable ordered
bulk stream, including format lists, unsuccessful results and empty
representations. This assignment has no size threshold. The following
operations implement the model in Section 4.12:
130 MWS_CLIPBOARD_PUBLISH
131 MWS_CLIPBOARD_REQUEST
132 MWS_CLIPBOARD_RESULT
133 MWS_CLIPBOARD_CANCEL
Every payload begins with the following 56-octet header. Integers are
unsigned and in network byte order. Offsets are relative to the start
of the payload; the common MWS Message header is not included.
Offset Size Field
0 4 window_id
4 4 application_id
8 4 seat_id
12 4 selection
16 8 offer_id
24 8 request_id
32 8 offset
40 4 status
44 4 flags
48 4 credit
52 4 reserved (MUST be zero)
56 * operation-specific body
selection is 0 for the ordinary clipboard and 1 for PRIMARY. These
selections MUST remain distinct. An endpoint without the requested
native selection reports UNSUPPORTED; it MUST NOT substitute another
selection. Other selection values are invalid in this specification.
window_id MUST be non-zero and identify a Window belonging to the
indicated Application in this Session. seat_id identifies the Seat
establishing clipboard authority. The Server assigns application_id;
Clients send zero and the Server supplies the authenticated route.
Portals preserve that route in replies and requests. The Server MUST
verify the Window's ownership before routing a Client publication or
request. A supplied identifier alone never authorises clipboard
access.
Format names are non-empty printable ASCII strings, compared exactly.
Media types [RFC6838] SHOULD be used where available. A format list
consists of names each followed by one NUL octet, including the final
name. A selected-format request contains one name without a NUL
terminator.
Representation bytes are opaque and MAY contain any octet value.
MWS_CLIPBOARD_PUBLISH flows from Client through Server to Portal and
advertises available formats without their contents. offer_id MUST be
non-zero for a non-empty list. request_id, offset, status, flags and
credit MUST all be zero. The offer identity names an immutable item;
replacement MUST use a fresh identity, increasing within its owning
Application and selection. Identities MUST NOT be reused during the
attachment. Exhaustion requires refusal, not wraparound.
An empty publication body withdraws only the specified offer. The
Portal also sends this withdrawal towards the Client when native
ownership is lost or publication is refused. Withdrawal of an older
offer MUST NOT withdraw its replacement. A Portal MUST NOT publish
unsolicited local clipboard contents to the Server.
MWS_CLIPBOARD_REQUEST flows in either direction. A Client requests
the Portal's native selection; a Portal requests bytes from an offer
previously published by a Client. request_id MUST be non-zero and
unique among that originator's requests for the attachment. status
and flags MUST be zero. credit MUST be non-zero and specifies the
maximum RESULT body length the requester can accept. It MUST fit
within the negotiated maximum payload after the 56-octet header.
offset plus credit MUST be representable in 64 bits.
A request with offer_id zero asks the Portal to enumerate the current
native offer. Its offset MUST be zero and its body MUST be empty.
A successful result returns a non-zero native offer identity and the
format list. That identity is scoped to the Portal attachment, Seat
and selection and MUST change when the native offer changes.
Otherwise the request body selects an advertised format and offset
specifies the first requested octet of that representation. A Server
MUST NOT route a request for an unadvertised Client format. The
Portal MUST apply native focus and clipboard access policy before
retrieving local contents. Knowledge of an earlier offer identity
does not bypass that policy. Following ownership changes, unavailable
representations MUST fail rather than return bytes belonging to a
replacement item.
MWS_CLIPBOARD_RESULT echoes application_id, window_id, seat_id,
selection, request_id and offset. It echoes offer_id except that a
successful enumeration supplies the newly discovered offer identity.
credit MUST be zero. Exactly one RESULT answers each request, with
no more body octets than its credit. Further segments require fresh
requests for the same offer and format at the next absolute offset.
status is one of:
0 OK Requested contents or formats are supplied.
1 UNAVAILABLE The offer or representation is no longer
available.
2 DENIED Native access or Session policy refuses this read.
3 RESOURCE Resources or receive credit cannot fulfil the
read.
4 CANCELLED The outstanding operation was cancelled.
5 UNSUPPORTED The selection or operation is not supported.
flags bit 0 (FINAL) means the representation ends after this body.
Bit 1 (FORMATS) marks a format-list result. All other bits MUST be
zero. A successful enumeration MUST set both bits and contain a
non-empty, complete format list at offset zero. It MUST NOT truncate
the list to satisfy credit: RESOURCE is returned instead.
Successful representation results MUST clear FORMATS. A non-final
body MUST be non-empty; a final body MAY be empty, including for an
empty representation. Offset arithmetic MUST be checked for overflow.
An unsuccessful result MUST have an empty body and only FINAL set.
Failure of a clipboard conversation is not failure of the Session.
MWS_CLIPBOARD_CANCEL flows from the requester and identifies the
request being abandoned using its original routing, selection, offer
and request identities. offset, status, flags and credit MUST be zero
and its body MUST be empty. No acknowledgement is required. The
supplier MUST cease pending work for that request. A RESULT racing
cancellation MAY arrive and MUST be consumed without acquiring new
authority. Cancellation does not withdraw the underlying offer.
Control and bulk have independent ordering. Endpoints MUST establish
pending request state before sending a request and MUST tolerate
cancellation, withdrawal or Window retirement overtaking a result.
A result MUST NOT acquire authority from its arrival order. Its
original correlation and the late-result rules below apply equally
across streams; no additional acknowledgement or ordering barrier
is implied. Credit bounds each response body, and further data
requires another request. Implementations MUST also bound aggregate
queued work so concurrent transfers cannot exhaust shared resources.
Receivers MUST correlate results with an outstanding request before
using their bodies, verifying routing, identity, offset, result kind
and granted credit. Unknown late results and cancellations are
ignored. A well-formed request racing offer or Window retirement
returns an unsuccessful result rather than terminating unrelated
Applications. Window destruction and attachment loss invalidate their
pending work; old request identifiers MUST NOT become valid after
reconnection.
On explicit detach, association loss, or Session replacement, the
attachment-specific offers and pending requests are invalidated as
specified in Section 4.12. This applies whether the Session enters
GRACE or DETACHED. A request that still identifies an invalidated
offer MUST receive status 1 (UNAVAILABLE); retained bytes do not
preserve authority to serve that offer. A replacement attachment
requires fresh offers and access checks. An invalidated offer or
request MUST NOT be revived by reusing its identifiers in the new
attachment.
Implementations MAY apply documented local response deadlines and
spool representations to temporary storage. They MUST release pending
resources on cancellation, failure or teardown. Data already
delivered to a native clipboard consumer cannot be revoked. These
Messages do not transfer files or confer authority to interpret
another machine's local paths as file-transfer requests.
5.2.2.3. Session D-Bus Bridge
This optional facility carries D-Bus [DBUS] conversations between
endpoint bridges on the Workstation and Portal. Both native Session
buses remain independent. A Session may contain any number of
Applications, from a single Application up to an entire desktop.
The MWS routing path does not interpret D-Bus interfaces, methods,
properties or application-specific bodies.
All five Messages below use the reliable ordered Control stream and
cross only the Portal association, Server <-> Portal. A Workstation
bridge acts within the authenticated Session under its account's
native authority. Its access to the Session bus MUST NOT confer the
privileged Server's identity. A Portal MUST NOT select an arbitrary
Workstation bus address, another Session, or the system bus.
The endpoints apply local policy to the peers, names and operations
represented on their native buses. These permissions are distinct
from MWS authentication. Neither a peer identifier nor a supplied
bus name grants authority. Missing native D-Bus support is ordinary
unavailability; it MUST NOT prevent unrelated Window, Input or Audio
use. This facility does not establish process sandboxing.
Each represented original peer has a separate native proxy connection
on the receiving bus. A native bus authenticates that proxy locally;
its credentials describe the proxy, not a remote PID or UID.
Endpoints MUST derive original sender identity from their native bus,
not an application-supplied SENDER field. Proxies MUST NOT be
exported through any bridge, including another attachment on the same
desktop. Otherwise two Workstations could acquire routes to each
other through a shared Portal without Session authorisation.
Every proxy connection MUST acquire a native provenance marker before
acquiring service aliases or originating application traffic. The
marker has the form org.mercurius.DBusBridge.Proxy.p followed by 32
lowercase hexadecimal digits, unique on that native bus. The proxy
MUST retain its marker until its native connection closes. It conveys
no access permission. Endpoint discovery and caller admission MUST
exclude owners of names in that marker namespace. Mere appearance
of a new unique name is not evidence of an original service: native
admission requires a selected well-known name or observed authorised
application traffic, after checking provenance. A local application
claiming a marker can exclude itself, but cannot gain bridge access.
Native unique names, well-known names and serials are local to their
bus. Endpoint bridges maintain the mappings required for calls,
replies, signals and owner lifetime. Bus-daemon operations, including
Hello, name ownership, credentials and match subscriptions, are
performed locally; org.freedesktop.DBus is not represented as a
remote peer.
Service activation is subject to the receiving endpoint's local
policy. An endpoint MAY activate a locally permitted destination
service on behalf of a remote caller. Permission to represent a
service or forward a method call MUST NOT by itself grant
unrestricted activation authority. An endpoint MUST NOT activate a
service outside that policy and MUST return an appropriate native
D-Bus error when activation is unavailable or refused and a reply is
expected. Bus-daemon activation operations remain local; they are
not forwarded as calls to a remote org.freedesktop.DBus peer.
Messages on the reserved org.freedesktop.DBus.Local interface or its
reserved object path MUST NOT cross this bridge. Interface-less calls
remain subject to policy; absence of an interface is not permission
to bypass an interface restriction.
This profile does not transport Unix file descriptors. Messages with
a nonzero UNIX_FDS field or any Unix-FD type, including signatures
contained in variants, are unsupported. Descriptor-bearing messages
MUST be refused with a native D-Bus error where a reply is possible;
local descriptor copies MUST be released. They MUST NOT be silently
lost or represented as integer values on the receiving host.
Local policy selects import names and export aliases. A proxy MUST
NOT replace an existing native name owner merely to create an
alias, nor queue to acquire a conflicting alias later. Renaming a
service does not make arbitrary strings in an application body
transparent. Endpoints MUST NOT rewrite embedded names, paths or URIs
in this profile. Implementations MUST make unsupported cases explicit
rather than claim universal bus merging.
MWS_DBUS_CAPABILITIES (140) -- Server <-> Portal
The Server sends first after establishment of the current
Session. The Portal replies once. Compatibility with this
protocol revision MUST already have been established as required
by Section 6.4; an endpoint MUST NOT probe an incompatible peer
with an unfamiliar Message. MWS_SESSION_INFO is unchanged.
Payload format (exactly 24 octets):
profile_version 4-octet unsigned integer
max_message_bytes 4-octet unsigned integer
receive_credit_bytes 8-octet unsigned integer
receive_credit_messages 4-octet unsigned integer
receive_peer_limit 4-octet unsigned integer
All integers in this facility use network byte order. Version 1
identifies this profile. Version 0 means unavailable and requires
all other fields to be zero. Other versions are not defined. An
unavailable Server receives an unavailable reply. Neither peer
sends PEER, MESSAGE or CREDIT until both advertisements declare
version 1. No second exchange occurs within this attachment.
For version 1 all limits MUST be nonzero. max_message_bytes is the
largest complete marshalled D-Bus message the advertiser accepts;
it MUST be at least 16 and at most max_payload_size minus 16.
receive_credit_bytes MUST be at least max_message_bytes plus 16.
These are actual receive admission limits, not a request that
the other endpoint allocate their advertised maximum eagerly.
receive_peer_limit limits simultaneously retained original peers
announced by the other endpoint. It excludes the advertiser's own
original peers and does not limit their lifetime allocation IDs.
MWS_DBUS_PEER (141) -- Server <-> Portal
Establishes or withdraws one original native bus owner and its
selected names. Payload format:
peer_id 8-octet unsigned integer
action 2-octet unsigned integer
status 2-octet unsigned integer
unique_name_len 2-octet unsigned integer
name_count 2-octet unsigned integer
unique_name unique_name_len octets
names name_count length-prefixed names
Each name consists of a 2-octet unsigned length followed by that
many octets. Names have no terminators. They MUST satisfy [DBUS]
syntax and its 255-octet bound. unique_name identifies an original
unique owner; names contains distinct well-known names currently
owned by that owner on the sending native bus. Neither value is
a local operating-system credential or an MWS Application ID.
A PEER payload MUST NOT exceed 4096 octets, and its exact length
MUST match the encoded fields. Oversized native descriptions are
unsupported rather than silently truncated.
Actions are 0 ANNOUNCE, 1 ACCEPT, 2 REJECT, 3 UPDATE and
4 WITHDRAW.
ANNOUNCE and UPDATE carry a nonempty unique_name and a possibly
empty names list, with status zero. All other actions have an
empty unique_name and names list. ACCEPT and WITHDRAW have status
zero. REJECT status is 1 POLICY, 2 UNAVAILABLE, 3 RESOURCE or 4
NAME_CONFLICT; other status values are undefined.
Server-origin peer IDs are odd; Portal-origin IDs are even. IDs
start at 1 and 2 respectively. Each subsequent ANNOUNCE in that
direction uses the preceding announced ID plus 2. IDs never wrap
or become reusable within an attachment. Thus receivers can
recognise retired IDs with a bounded high-water mark rather than
retaining an unbounded tombstone set. An original unique owner has
at most one live peer ID per origin and attachment. ANNOUNCE,
UPDATE and WITHDRAW are sent only by that peer's origin. ACCEPT
and REJECT are sent only by its receiver. A new ANNOUNCE above the
peer limit MUST be rejected as RESOURCE without creating a proxy.
Rejected and withdrawn identities remain retired.
The receiver authorises an ANNOUNCE and establishes the native
representation before replying ACCEPT. Until that reply reaches
the origin, the origin MUST NOT send MESSAGE concerning that
peer. The receiver may originate such traffic only after sending
ACCEPT, ordered before that traffic in the same direction. A
rejected announcement establishes no representation.
The receiver chooses local aliases under its own policy; it MUST
NOT treat the original names as permission to acquire them.
An UPDATE replaces the selected-name list for the same original
unique owner. A changed unique owner requires a new peer ID.
There is at most one outstanding ANNOUNCE or UPDATE per peer;
further native name changes may be coalesced until its reply.
The receiver replies ACCEPT after applying the replacement, or
REJECT and withdraws that representation completely. It MUST NOT
retain aliases from a rejected update. Existing conversations may
continue while an UPDATE is pending, subject to current policy.
WITHDRAW retires a peer, including an announcement or update still
awaiting its reply. The origin stops originating traffic for that
identity before sending WITHDRAW. The receiver removes aliases,
closes its proxy connection and fails that peer's pending work.
Replies to an offer overtaken by WITHDRAW are consumed without
recreating state. Native owner replacement or disappearance MUST
NOT transfer old conversations to a new owner.
MWS_DBUS_MESSAGE (142) -- Server <-> Portal
Payload format:
source_peer_id 8-octet unsigned integer
destination_peer_id 8-octet unsigned integer
message remaining payload octets
message is exactly one complete binary D-Bus message, including
its native header, in the byte order identified by that header.
Its size MUST NOT exceed the receiver's max_message_bytes. The
MWS stream and payload limits still apply. Transport fragmentation
under Section 5.1.1 does not change this logical Message.
source_peer_id MUST identify an accepted, live original peer
belonging to the sender's allocation direction. A nonzero
destination_peer_id identifies an accepted original peer on the
receiving side. Zero is permitted only for an authorised D-Bus
broadcast signal. Endpoints MUST validate the D-Bus frame and
correlate its native sender with the announced original owner.
Peer descriptions and incoming destination header text MUST NOT
select another bus or bypass the receiving endpoint's policy.
The native adapters translate SENDER, DESTINATION, serial and
reply-serial headers as required by the two buses. Application
bodies remain opaque. Unknown header fields MUST be handled as
required by [DBUS], not interpreted as extra routing authority.
Native proxy serial allocation MUST NOT conflate conversations
from different original peers. A reply or error is accepted only
for its actual outstanding peer and call; a bare serial is not
sufficient authority. A MESSAGE referencing a retired source or
destination is consumed without delivery or recreation, still
consuming and releasing its data credit. Such traffic can race
rejection of an UPDATE in the opposite direction. Wrong-direction
and never-announced IDs remain invalid. Calls still waiting on a
retired peer are failed through the native D-Bus conversation.
Native calls and signals are selected by local policy. A bridge
MUST NOT forward its own relayed broadcasts back to their origin
or re-export a proxy as a newly discovered native peer. Signals
remain subject to native subscriptions on the destination bus.
MWS_DBUS_CREDIT (143) -- Server <-> Portal
Payload format (exactly 16 octets):
released_bytes 8-octet unsigned integer
released_messages 8-octet unsigned integer
Counters are cumulative within this attachment and direction,
starting at zero. Each MESSAGE consumes one message credit and
its entire payload length in byte credit, including the 16-octet
routing prefix. Let S be cumulative sent work, R cumulative
released work and C the initial grant. Admission requires both
S_bytes - R_bytes + payload_length <= C_bytes and
S_messages - R_messages + 1 <= C_messages, using checked unsigned
arithmetic. A sender MUST NOT spend credit which has not arrived.
Credit is returned only after releasing charged receive storage.
An endpoint MUST eventually send changed cumulative credit even if
no subsequent data arrives; it MUST NOT wait for a new MESSAGE
whose admission depends on that credit. Passing data to an
unbounded native write queue does not release that responsibility.
Native queued writes and pending call maps MUST have bounded
ownership and failure behaviour. Write completion does not
establish remote execution or call completion. Endpoints MUST NOT
retain message credit until a method reply arrives: pending-call
state has a separate bounded budget, so calls in both directions
cannot deadlock waiting for replies.
A counter MUST NOT decrease, exceed the corresponding cumulative
work sent, or wrap. An equal cumulative update is harmless.
Before counter exhaustion the endpoint closes this bridge. PEER,
CREDIT and CLOSE do not consume MESSAGE credit. Each endpoint
MUST provide separately bounded management capacity, so exhaustion
of data credit cannot prevent credit release or withdrawal.
It MUST enforce peer and management limits without an unbounded
queue; inability to maintain them closes this optional bridge.
MWS_DBUS_CLOSE (144) -- Server <-> Portal
Payload format (exactly 8 octets):
reason 4-octet unsigned integer
reserved 4-octet unsigned integer, zero
Reasons are 0 NORMAL, 1 UNAVAILABLE, 2 POLICY, 3 RESOURCE,
4 INVALID and 5 COUNTER_EXHAUSTED. Other values are undefined.
The first local or received CLOSE stops new bridge work, withdraws
proxies and fails pending native conversations. A receiver which
has not sent CLOSE sends one in response. Each endpoint sends at
most one CLOSE. Facility traffic racing closure is consumed
without native delivery; it MUST NOT recreate peers or credit.
Endpoints need not retain a live native bus merely to drain this
exchange. Closure of this facility is not closure of MWS Session
resources unrelated to it.
Before capabilities complete, CLOSE may report failure after this
endpoint's advertisement; it ends this attachment's facility.
Malformed facility payloads, invalid ownership or excess credit
are refused as INVALID and MUST NOT widen native access. Ordinary
policy rejection and native unavailability are not protocol
violations by unrelated Applications. Structural MWS framing and
Session-authority errors remain subject to Section 5.9.
Detach, association loss and Session replacement invalidate the whole
bridge, its peer IDs, credit and pending conversations, including
when the underlying association remains open for Session selection.
Both endpoints MUST quiesce old bridge producers before committing a
different Session on that association. Already queued facility
traffic MUST be delivered before the Session-selection boundary in
its Control direction or discarded before that boundary. It MUST
NOT be emitted into the replacement attachment. A new attachment
requires fresh capability advertisements, peer discovery and policy
checks.
An old call whose completion is unknown MUST NOT be replayed. Closing
a native conversation or bridge does not cancel an operation which
the remote service may already have performed.
5.2.3. Window Lifecycle (200-299)
Window creation, destruction, mapping, and configuration are managed
through the following Messages. A user action at a Portal does not
make the Portal the owner of the resulting Window operation. Input is
delivered to the workstation; the Client or server-side
window-management policy then originates any required request.
MWS_CREATE_WINDOW (type=200) -- Library -> Server
(client channel)
Reports the Client's request to create a new top-level Window
within its Session. This Message is not sent on the Portal
association.
Payload format:
request_id 4-octet unsigned integer
width 4-octet unsigned integer
height 4-octet unsigned integer
title_len 1-octet unsigned integer
title title_len octets
request_id is a non-zero value selected by the Library to
identify this request; it is not a definitive window_id. A
Library MAY place a provisional Window identifier in this
field, but the Server MUST treat it only as request correlation
data. width and height are in pixels and MUST be non-zero.
title is UTF-8 and is not NUL-terminated. The payload length
MUST equal 13 + title_len.
MWS_WINDOW_CREATED (type=201) -- Server -> Library
(client channel)
-- Server -> Portal
(Portal association)
Confirms Window creation and supplies its window_id, owning
application_id, and initial geometry. The response retains the
identifying data from the original request so the Library can
match concurrent requests; the Portal uses it to create the
corresponding presentation surface.
Payload format:
window_id 4-octet unsigned integer
application_id 4-octet unsigned integer
request_id 4-octet unsigned integer
width 4-octet unsigned integer
height 4-octet unsigned integer
title_len 1-octet unsigned integer
title title_len octets
window_id is assigned by the Session and MUST be non-zero. It
is definitive: the Library MUST replace any provisional value
with this identifier. Window addressing is scoped by the tuple
(association_id, session_id, window_id), and only the Session
may assign its window_id component. For ordinary creation,
request_id, width, height, title_len, and title MUST be copied
unchanged from MWS_CREATE_WINDOW. During resume reconstruction,
request_id MUST be zero and the other fields describe the
current Window, as in Section 5.2.2.1. The payload length MUST
equal 21 + title_len.
application_id MUST be the non-zero, Session-scoped identifier
assigned by the Server to the Application owning this Window.
All Windows owned by that Application carry the same value,
including during resume reconstruction. A Portal MAY use it
for native Window grouping, but it grants no authority and
MUST NOT be treated as a process identifier or desktop
application identity. Identical values in different Sessions
do not identify one Application.
MWS_DESTROY_WINDOW (type=202) -- Library -> Server
(client channel)
-- Portal -> Server
(Portal association)
Requests definitive destruction of a Window in the Session.
A Library sends it for a Client-owned Window. A Portal sends it
when a native surface, such as a dismissed popup, cannot remain
presented. An ordinary native close gesture MUST instead use
MWS_WINDOW_CLOSE_REQUEST so the Application can handle or veto
the request. The Server validates the Window and reports its
destruction with MWS_WINDOW_DESTROYED. A Portal requesting
destruction of its Session's DESKTOP Window also requests the
end of that Session.
Payload format:
window_id 4-octet unsigned integer
MWS_WINDOW_DESTROYED (type=203) -- Server -> Library
(client channel)
-- Server -> Portal
(Portal association)
Reports that the Server has destroyed a Window. The Server
notifies the Portal and, when the Portal requested destruction,
the owning Library. A Server MAY accept this Message from a
legacy Portal as a definitive destruction request. A legacy
Portal close of a DESKTOP Window MUST still end the Session,
including after that Window has been destroyed. Current Portals
close the Session container with MWS_SESSION_CLOSE_REQUEST.
Client-initiated destruction of a desktop Window does not
itself request Session termination.
Payload format:
window_id 4-octet unsigned integer
MWS_MAP_WINDOW (type=204) -- Library -> Server
(client channel)
and Server -> Portal
(Portal association)
Reports that the Client requested a Window become visible.
After accepting the Message, the Server sends it to the Portal.
Payload format:
window_id 4-octet unsigned integer
MWS_UNMAP_WINDOW (type=205) -- Library -> Server
(client channel)
and Server -> Portal
(Portal association)
Reports that the Client requested a Window become hidden.
After accepting the Message, the Server sends it to the Portal.
Payload format:
window_id 4-octet unsigned integer
MWS_CONFIGURE_WINDOW (type=206) -- Portal <-> Server
(Portal association)
-- Server -> Library
(client channel)
Reports or establishes Window geometry. A Portal reports actual
geometry changes made by its native window system to the
Server. In a desktop Session, the Server's WindowManager owns
placement and maximisation policy and MAY send its resulting
geometry decisions to the Portal for native realisation. The
Server also delivers accepted geometry to the owning Library,
which translates it for the Client. Native constraints may
prevent an exact realisation; the Portal MUST report the actual
resulting geometry rather than treating delivery as native
completion.
During resume reconstruction, the Server sends retained
geometry to the Portal. The Portal defers any resulting native
geometry notification until after MWS_SESSION_RESUME_COMPLETE.
Payload format:
window_id 4-octet unsigned integer
x 4-octet signed integer
y 4-octet signed integer
width 4-octet unsigned integer
height 4-octet unsigned integer
width and height are in pixels and MUST be non-zero. The
payload length MUST be exactly 20 octets.
MWS_FOCUS_WINDOW (type=207) -- Portal <-> Server
(Portal association)
-- Server -> Library
(client channel)
Reports or establishes that a Window has gained or lost
keyboard focus. A Portal reports a native user focus transition
to the Server. The Server's WindowManager retains the
authoritative Session focus and sends its resulting decision to
the Portal for native realisation. The Server also notifies the
Library, which translates the transition for the Client.
Messages on the Portal association travel on the reliable
ordered Input stream. This orders an accepted focus transition
before any subsequent input event directed to the Window.
Delivery from the Server to the Library uses the Client
channel.
Payload format:
window_id 4-octet unsigned integer
focused 4-octet unsigned integer
focused MUST be zero when the Window lost focus and one when it
gained focus. Other values are invalid. The payload length MUST
be exactly 8 octets.
Control and Input are independently ordered. A Window's
destruction can therefore arrive before an earlier focus-loss
decision. After validating the complete payload, a Portal MUST
consume a Server-originated focus-loss Message for an absent
Window without native action or terminating the association.
Focus gain received before its Window announcement follows the
deferred Input rules in Section 5.4. Neither rule relaxes
Server validation of Portal-originated Messages.
MWS_SWAPCHAIN_REVOKED (type=208) -- Server -> Library
(client channel)
Indicates that a Window's swapchain has been revoked due
to policy, timeout, or resource constraints. The Library must
cause the Client to recreate its presentation resources and
redraw the Window through ordinary graphical API semantics.
Payload format:
window_id 4-octet unsigned integer
MWS_WINDOW_STATE (type=209) -- Library -> Server
(client channel)
-- Server -> Portal
(Portal association)
Reports the Client-selected state and size constraints of one
Window. After accepting the Message, the Server records the
state and sends it to the Portal. The Server also sends the
current state of every live Window while reconstructing a
resumed Session.
Payload format:
window_id 4-octet unsigned integer
flags 4-octet unsigned integer
minimum_width 4-octet unsigned integer
minimum_height 4-octet unsigned integer
maximum_width 4-octet unsigned integer
maximum_height 4-octet unsigned integer
Bit 0 of flags is FULLSCREEN. When set, the Portal enters its
native fullscreen state and reports the resulting extent using
MWS_CONFIGURE_WINDOW so the Client can render at that native
resolution.
Bit 1 of flags is FULLSCREEN_SCALED. It is valid only when
FULLSCREEN is also set. The Portal then retains the Client's
logical content extent, aspect-fits it into the native
fullscreen extent, and maps absolute Input coordinates back
into the Client's logical coordinate space. Scaling applies
equally when the native extent is larger or smaller than the
Client content.
All other flag bits MUST be zero. A zero minimum or maximum
dimension means that no bound is specified on that axis. Equal
non-zero minimum and maximum dimensions describe a fixed-size
Window. When both bounds on an axis are non-zero, the minimum
MUST NOT exceed the maximum. Fullscreen temporarily suspends
these constraints. The payload length MUST be exactly 24
octets.
MWS_WINDOW_RELATION (type=210) -- Library -> Server -> Portal
(client channel, then
Portal association)
Describes a Window's role and its relationship to an optional
parent Window. The Server validates and retains the
relationship before forwarding it to the Portal.
Payload format:
window_id 4-octet unsigned integer
parent_id 4-octet unsigned integer
role 4-octet unsigned integer
flags 4-octet unsigned integer
x 4-octet signed integer
y 4-octet signed integer
role is 0 for an independent top-level Window, 1 for a
transient Window, 2 for a popup, 3 for the Session desktop, and
4 for a desktop shell panel. Other values are invalid. A role 3
Window establishes the fullscreen workspace representing the
Session at the Portal. It MUST be presented without an
independent native decoration, and a Session MUST NOT contain
more than one live role 3 Window. Bit 0 of flags requests modal
treatment. Bit 1 requests a passive popup: a visual, such as
drag feedback, which MUST NOT receive pointer, keyboard, or
touch input, acquire focus, or establish an input grab. Input
MUST reach the otherwise eligible Window beneath it. Bit 1 is
valid only for role 2 and MUST NOT be combined with bit 0. Bit
2 requests desktop-relative popup placement: x and y are Portal
desktop coordinates and MUST NOT move with the parent. Bit 2 is
valid only for roles 2 and 4 and MUST NOT be combined with bit
0. A role 4 Window MUST name the role 3 Window in the same
Session as its parent and MUST set bit 2. The parent MUST
belong to the same Application, unless the Server has accepted
the exact Panel delegation defined in Section 5.2.3.4. Window
ownership does not change. Desktop placement is subject to
Portal display capabilities and policy; it does not grant
desktop focus or reserved screen space. The Server's
WindowManager MAY exclude an authorised, mapped Panel's
occupied area from the work area used for ordinary Window
placement and maximisation. This is Session policy, not
authority conferred by declaring a Panel relationship. A work
area does not change the full desktop extent or the Portal's
reported Seat geometry. Bit 3 declares that the Client's pixels
include its decoration. Bit 4 requests a Portal-provided
decoration. Bits 3 and 4 are mutually exclusive and are valid
only for roles 0 and 1. When neither bit is set, the Window is
intentionally undecorated. Implementations SHOULD prefer bit 3
when the Client toolkit can provide a complete decoration. A
Portal MUST NOT add another decoration to a Window carrying bit
3. An Application MAY update a desktop popup's x and y by
sending another relationship with the same window_id,
parent_id, role, and flags. The Portal MUST preserve the
Window's native identity, content, and any ongoing input grab
when applying this movement. All other flag bits MUST be zero.
For roles 0 and 3, parent_id MUST be zero. Role 3 flags MUST be
zero; role 0 flags may contain only bit 3 or bit 4. For roles
1, 2, and 4, parent_id MUST identify a different live Window in
the same Session. Roles 1 and 2 require the same Application
owner; role 4 permits only the explicit delegation exception
above. Role 1 flags may additionally contain bit 0. Cyclic
relationships MUST be rejected. The payload length MUST be
exactly 24 octets.
For a related Window without bit 2, x and y are offsets from
its parent's content origin. For roles 0 and 3, they are
advisory Portal placement coordinates. Native placement and
modal behaviour remain subject to Portal policy and MUST NOT
confer authority over unrelated Windows or the Portal desktop.
A new Window is independent until a valid relationship is
received. Removing a parent MUST also remove or clear
relationships which refer to it.
MWS_WINDOW_TITLE (type=211) -- Library -> Server
(client channel)
-- Server -> Portal
(Portal association)
Replaces the user-visible UTF-8 title of an existing Window.
This Message permits titles assigned or changed after native
Window creation to reach the Portal without recreating that
Window.
Payload format:
window_id 4-octet unsigned integer
title_len 2-octet unsigned integer
title title_len octets
title is well-formed UTF-8 without a terminator and MUST NOT
exceed 255 octets. An empty title is valid. The payload length
MUST equal 6 + title_len. The Server MUST verify that the
sending Application owns window_id before recording and
forwarding the replacement.
MWS_WINDOW_ICON (type=212) -- Library -> Server -> Portal;
Server -> desktop adapter
Replaces the icon of an existing Window. The Server MUST verify
that the sending Application owns window_id before retaining
and forwarding the replacement. This is Window metadata, not
Render content, and travels on the Control stream.
For a mapped ordinary top-level, the Server also sends its
current icon to the registered desktop task adapter, including
in the initial task snapshot. The adapter uses these pixels
when no local application icon is available.
Payload format:
window_id 4-octet unsigned integer
edge 2-octet unsigned integer
reserved 2 octets, MUST be zero
rgba edge * edge * 4 octets
The image is square, top row first, tightly packed, with
channel octets R,G,B,A and straight (not premultiplied) alpha.
edge MUST NOT exceed 256. This wire limit bounds Window
metadata separately from arbitrary-size Render content. The
exact payload length is 8 + edge * edge * 4. edge zero, with no
pixels, restores the Portal's Mercurius fallback icon. New
Windows use that fallback until an icon is supplied. Recipients
MUST reject malformed extents and reserved bits before
interpreting or allocating pixel storage.
The Portal MAY adapt the icon to native decoration facilities.
A native environment without per-Window icon support MAY retain
its default icon. Icon updates MUST NOT change Application
identity, focus, geometry or authority. Recreated Window
identities need a new icon Message; hiding or resizing a Window
does not clear it.
Examples of native integration are the X11 _NET_WM_ICON
property [EWMH] and the optional Wayland xdg-toplevel-icon-v1
protocol [XDG-ICON]. These are local presentation mechanisms,
not MWS wire encodings. The Portal converts the validated RGBA
pixels to the native format; no remote filesystem path or
desktop icon name needs to be resolved. Compositor support and
policy determine whether a native icon is displayed.
MWS_WINDOW_CURSOR (type=213) -- Library -> Server -> Portal
Selects a standard cursor or static custom cursor image for
an existing Window. The Server MUST verify that the sending
Application owns window_id before retaining and forwarding
the selection on the Control stream.
The common payload prefix is:
window_id 4-octet unsigned integer
shape 4-octet unsigned integer
For a standard shape, the payload is exactly eight octets.
Standard shapes are:
0 default arrow 11 forbidden
1 text insertion 12 contextual help
2 crosshair 13 open hand
3 pointing hand 14 closed hand
4 east-west resize 15 hidden
5 north-south resize 16 column divider
6 NW-SE resize 17 row divider
7 NE-SW resize 18 upward arrow
8 move in any axis 19 drag copy
9 wait 20 drag move
10 working/progress 21 drag link
Shape 22 selects a custom image and appends:
width 2-octet unsigned integer
height 2-octet unsigned integer
hotspot_x 2-octet unsigned integer
hotspot_y 2-octet unsigned integer
rgba width * height * 4 octets
The image is top row first, tightly packed, with channel
octets R,G,B,A and straight (not premultiplied) alpha. Width
and height MUST each be between 1 and 256 inclusive. The
hotspot identifies the pointer position within the image:
hotspot_x MUST be less than width and hotspot_y MUST be less
than height. The exact payload length is 16 + width * height
* 4. Recipients MUST validate the complete extent, hotspot
and payload length before allocating or interpreting image
storage. This bound limits cursor metadata independently of
Render content; cursor images do not contain filenames or
encoded image formats.
Custom image dimensions and hotspots share an image-pixel
coordinate grid. The Portal MAY adapt the image to native
cursor sizing or display scale, preserving its aspect ratio
and the hotspot's alignment with the pointer position. A
native environment unable to display the artwork MAY use its
default arrow.
Other shape values are unassigned and MUST be rejected.
Shape zero is the initial state. A new selection replaces
the previous shape and any custom image. The selection
persists across hide, show and pointer leave/enter until
replaced or the Window is destroyed. It MUST NOT change
focus, pointer position, grabs or the selection belonging to
another Window. A hidden pointer mode takes precedence
without discarding the retained shape.
For standard shapes, the Portal supplies native artwork and
sizing. If a visible shape is unavailable, it MAY use its
default arrow; shape 15 MUST hide the cursor. Updates
describe semantic state, not pointer movement, and MAY
coalesce to the latest selection. The Server retains custom
pixels with the Window and includes the complete selection
in Session reconstruction. This Message specifies a static
selection, not animation frames or animation timing.
MWS_WINDOW_IDENTITY (type=214) -- Library -> Server
(client channel)
-- Server -> Portal
(Portal association)
Replaces the desktop application identity of an existing
Window. This presentation metadata permits a Session desktop
or the Portal's native desktop to associate the Window with
its local desktop-entry database, task metadata and icon theme.
It is distinct from the Session-scoped Application identifier,
application_id, and MUST NOT grant authority, select an
executable, or cause a desktop entry to be executed.
Payload format:
window_id 4-octet unsigned integer
identity_len 2-octet unsigned integer
identity identity_len octets
identity is well-formed UTF-8 without a terminator and MUST NOT
exceed 255 octets. An empty identity clears the value. The
payload length MUST equal 6 + identity_len. The Server MUST
verify that the sending Application owns window_id before
recording the replacement and forwarding it to the attached
Portal on reliable ordered Control. The Portal MUST verify
that window_id belongs to its attached Session before applying
native presentation metadata. Clearing the identity MUST clear
the corresponding native association or restore its fallback.
A peer-supplied identity is not permission to open a pathname
or execute a desktop entry. The metadata MUST NOT be sent to
another Session or used as evidence of Application authority.
Session reconstruction MUST include the retained current
identity, including an empty value, under Section 5.2.2.1.
MWS_WINDOW_CLOSE_REQUEST (216), Portal -> Server and Server ->
Application, requests an ordinary close of the Window. Its
four-octet payload contains a non-zero window_id. The Server
MUST verify that the Window belongs to the Portal's Session
before forwarding the request. The Application MAY handle or
veto it and remains responsible for destroying its Window. The
Portal MUST present it until the Server reports destruction.
MWS_WINDOW_SIZE_REQUEST (217), Library -> Server -> Portal,
asks for a preferred content extent. Its payload is exactly
twelve octets: window_id, width and height, each an unsigned
four-octet integer in network byte order. The identity and both
dimensions MUST be non-zero. It travels on reliable ordered
Control.
The Server MUST verify that the sending Application owns the
Window in its authenticated Session, regardless of Window role.
The request changes no role, relationship, placement or input
authority. Resizing a popup MUST preserve its identity and any
active input grab. No pointer gesture is required. Native
policy remains authoritative: the Portal MUST respect size
constraints and native maximised or fullscreen state. It MAY
refuse a preferred extent, including one outside the native
representation's range.
Every accepted request MUST be settled by MWS_CONFIGURE_WINDOW
reporting actual geometry, even if unchanged. Acceptance alone
MUST NOT change the Library's rendering extent. Several pending
requests MAY be settled at the same final actual geometry, but
each requires a completion. Requests MUST NOT be replayed on
resume. Peers MUST establish support for this protocol revision
before using this contract; earlier revisions use different
opcode assignments. The implementation-version fields do not
negotiate that support.
MWS_WINDOW_STATUS (218), Portal -> Server -> owning
Application, reports observed native state on reliable ordered
Control. Its payload is exactly 12 octets:
window_id 4-octet unsigned integer
known 4-octet unsigned integer
flags 4-octet unsigned integer
Bit 0 means maximised on both axes; bit 1 means minimised; bit
2 means fullscreen. All other bits MUST be zero. flags MUST be
a subset of known. A bit absent from known has an unknown
value, not a false value. Native interfaces MUST leave a known
bit clear when they cannot observe the corresponding state.
Request submission MUST NOT be reported as an observed state
transition. Observations include changes made through the
native desktop, not only Application requests. Unchanged
observations may be coalesced. Geometry remains a separate
configure exchange.
The Server MUST accept this Message only from the Portal
attached to the Window's Session and route it only to the
owning Application. It MUST NOT accept Application-originated
status or interpret an observation as authority to change
Window ownership or lifetime. Status is transient native
information and MUST NOT be replayed on Session resumption; the
new Portal supplies fresh observations. The opcode assignments
in this revision are wire-incompatible with earlier revisions.
Peers MUST establish support for this protocol revision during
admission as specified in Section 5.2.1.
Every multi-octet field in Section 5.2.3, including its subsections,
is in network byte order. Except for MWS_CREATE_WINDOW, every Window
lifecycle payload begins with a non-zero window_id. A recipient MUST
reject an incorrect payload length, a zero identifier, invalid UTF-8,
or a Window outside the permitted Session scope.
MWS_WINDOW_FRAME_EXTENTS (219), Portal -> Server, reports observed
margins of a Portal-provided fallback decoration in a desktop
Session. It travels on reliable, ordered Control. Its payload
is exactly twenty octets, consisting of five unsigned
four-octet integers in network byte order:
window_id, left, right, top, bottom
window_id MUST be non-zero. The margins describe the native
frame outside the Window's content rectangle, in Session
pixels. They are observations, not placement requests, and
confer no Window-management, input or screen-reservation
authority. They MUST NOT alter the reported Seat or full
desktop geometry.
The Portal sends a report after successfully creating a
fallback frame and whenever its margins change, including
before first mapping. Unchanged margins MUST NOT be reported in
response to content geometry changes alone. The Server MUST
validate the report against the current attachment and the
Window's eligible top-level or transient server-decoration
relationship. Reports MAY be accepted while the Window is
unmapped. After validating the complete payload, the Server
MUST consume a report for an already-destroyed Window without
action; opposite-direction Control traffic can cross during
ordinary destruction.
The Server retains these observations separately from frames
supplied by its delegated renderer. Renderer measurements take
precedence. Margin sums and outer-geometry calculations MUST be
checked for overflow; margins need not be smaller than content
dimensions. Observations belong to the current attachment and
MUST be discarded when it ends or is replaced. They MUST NOT be
replayed during resume; the new Portal reports its own frames.
Peers MUST establish support for this protocol revision before
using the report; earlier peers do not implement this contract.
5.2.3.1. Window Identifier Scope
Window identifiers are scoped to the Session that created them. A
Portal MUST NOT reference, manipulate, or query Windows belonging to
any other Session. For every wire Window Message received from a
Portal association, the server MUST validate that the window_id
belongs to the Session associated with that SCTP association.
If a portal attempts to reference a window outside its session, the
server MUST reject the message with MWS_ERROR_SESSION (type=702,
fatal=0). The server MUST NOT reveal the existence, geometry, focus
state, or any other attributes of windows belonging to other
sessions.
A window_id MUST be unique among live Windows in its Session. The
same numeric value MAY occur in another Session because the Session
context is part of the Message address. The server MUST never resolve
a window_id outside the Session selected by the authenticated
association, regardless of numeric equality.
These rules ensure that windows are private to the session that owns
them and that portals cannot observe or interfere with the graphical
state of other users.
5.2.3.2. Desktop Decoration
A desktop Session MAY delegate native theme rendering to a
local renderer. The Server retains Window-management authority.
Ordinary application Sessions continue to use the Portal's
native window manager. Windows supplying client decorations
MUST NOT receive a second frame. These Messages use the Control
stream; pixels below are frame metadata, never a replacement
for Window Render content.
Every payload starts with this 64-octet network-order prefix:
window_id 4-octet unsigned integer
operation 4-octet unsigned integer
revision 4-octet unsigned integer
flags 4-octet unsigned integer
width 4-octet unsigned integer
height 4-octet unsigned integer
x 4-octet signed integer
y 4-octet signed integer
left 4-octet unsigned integer
top 4-octet unsigned integer
right 4-octet unsigned integer
bottom 4-octet unsigned integer
root_x 4-octet signed integer
root_y 4-octet signed integer
button 4-octet unsigned integer
buttons 4-octet unsigned integer
body remaining payload octets
window_id MUST be non-zero. Fields without a meaning for the
selected opcode are ignored; they convey no additional
authority.
MWS_DECORATOR_READY (227), renderer -> Server, registers the
renderer using its own, unmapped registration Window. There is
no body. The Server MUST verify Application ownership of that
Window and bind the delegated renderer to that Application's
authenticated Channel. It MUST reject a competing registration
while the renderer exists. Removing the registration Window
revokes the delegation. A Portal MUST NOT register a renderer
or submit frames/actions. Other Applications MUST NOT
impersonate the bound renderer. The delegation grants no access
to another Session. A Server MAY impose additional local
renderer policy.
MWS_DECORATION_REQUEST (228), Server -> renderer, describes one
managed Window (operation 1), or retires its frame (operation
2). A description carries content width/height and an
unterminated UTF-8 title in body, with the same 255-octet limit
as Window titles. flags bit 0 means active; bit 1 means
maximised; bit 2 means shaded. Shading is Session policy, not
a Client size or mapping change. revision identifies this
description and MUST be echoed by frames rendered from it.
A retirement has no body.
The Server changes revision whenever authoritative theme inputs
change. A receiver MUST discard a frame whose revision does not
match its current description.
MWS_DECORATION_FRAME (229), renderer -> Server -> Portal, carries
outer width/height and the four margins around application
content. left+right MUST be less than width, and top+bottom
less than height. body contains tightly packed, top-row-first,
premultiplied RGBA8 pixels, ordered as four strips: full-width
top, full-width bottom, then left and right between those rows.
A zero-width or zero-height strip has no pixels. The exact body
size in octets is:
4 * (width * (top + bottom)
+ (left + right) * (height - top - bottom))
Receivers MUST check the arithmetic and exact payload length
before allocation. The enclosed content extent MUST match the
current Window description. Frame updates do not themselves
alter content geometry, focus, mapping, or ownership. The
Portal MUST display the frame around that Window. It SHOULD
preserve pixel alpha where the native presentation environment
supports it.
MWS_DECORATION_INPUT (230), Portal -> Server -> renderer, reports
motion (operation 1), press (2), release (3), or leave (4). x/y
are relative to the outer frame; root_x/root_y are relative to
the Session desktop. button identifies the changed button (1
primary, 2 middle, 3 secondary); buttons is the post-event bit
set, bit 0 identifying the primary button. revision identifies
the displayed frame. There is no body. The Server MAY consume
pointer movement during its own active move or resize
operation.
MWS_WINDOW_ACTION (215) -- renderer -> Server
-- Application -> Server
Requests a Window-management action. The delegated renderer may
request close (1), toggle maximise/restore (2), begin move (3),
begin resize (4), minimise (5), toggle shade/unshade (8), begin
menu Move (9), or begin menu Resize (10).
Shading is permitted only for a mapped, server-decorated Window
with a usable nonzero-height title strip. It retains the full
content rectangle, mapping and focus; only native content
visibility changes. Move remains available while shaded;
resize is refused. Maximise or fullscreen clears shading;
minimisation retains it. root_x/root_y identify the
initiating pointer position. For resize, flags names edges:
left=1, top=2, right=4, bottom=8. Opposite edges MUST NOT be
combined and at least one edge MUST be selected. There is no
body. The Server MUST validate each request against current
Session state; only the Server changes Window geometry or
lifetime. Operations 3 and 4 require an active primary-button
interaction. Accepted geometry is published using
MWS_CONFIGURE_WINDOW.
Menu Move and Resize are desktop-independent, Session-owned
interactions. Only the current delegated renderer may request
them for an eligible managed Window using its current frame
revision. No primary button needs to remain held. flags, button
and buttons MUST be zero. Renderer-supplied geometry and
pointer fields are ignored; capture admission supplies the
observed initial pointer and content origin. Resize initially
adjusts the bottom-right corner. Pointer motion or arrow keys
adjust geometry subject to Window constraints. A primary button
press or Enter accepts the current geometry; Escape restores
the geometry retained when the operation began. Input consumed
by this interaction MUST NOT be delivered to the Application.
The Server cancels the interaction on Window withdrawal, loss
of renderer delegation or Portal detachment. Menu requests MUST
NOT be retained for replay or resume and confer no
Window-management authority on Applications.
In any Session, an Application MAY send MWS_WINDOW_ACTION to
the Server to begin move (operation 3) or resize (operation 4)
of its own client-decorated top-level or transient Window.
Outside a desktop Session, it MAY additionally request minimise
(5), set maximised (6), or restore from maximised (7) for that
Window. There MUST NOT be a body. For move or resize, button
MUST be 1. For operations 5, 6 and 7, button, flags and
revision MUST be zero; no initiating pointer gesture is
required. Operations 6 and 7 request explicit states, never a
toggle. Native policy may refuse them. These operations neither
change Application mapping nor confer renderer authority.
Native observations return through MWS_WINDOW_STATUS; accepted
geometry continues to return through MWS_CONFIGURE_WINDOW. For
move, flags MUST be zero; for resize, flags selects one edge or
two adjacent edges as above. For gesture requests, revision
carries the timestamp of the initiating primary-button input
event. Other fields are ignored and convey no authority. The
Server MUST verify Application ownership, Window role and
decoration policy before forwarding the request to the Portal.
This exception grants no renderer authority.
For Application move or resize, the Portal MUST match the
Window and timestamp against a primary-button press still
active locally. It MUST derive native coordinates and any
compositor gesture serial from its own input state, never from
Application data. Requests MUST NOT be retained for replay or
resume. Outside a desktop Session, missing or expired gestures
are ignored, native window-management policy may refuse either
operation, and native geometry changes return through
MWS_CONFIGURE_WINDOW. Acceptance is not completion. This
direction extends the earlier renderer-only and top-level-move
contracts without changing the wire layout; earlier peers do
not support the complete contract.
Within a desktop Session, Application move and resize use the
Session-owned capture conversation below. The Server MUST
retain geometry policy and MUST NOT delegate desktop-child
placement to the Portal's native window manager. It MUST send
the validated MWS_WINDOW_ACTION immediately before the matching
MWS_WINDOW_INTERACTION_BEGIN as consecutive logical Messages on
ordered Control. The Portal MUST associate the action only with
that immediately following Begin for the same Window,
corresponding Move or Resize mode, and resize edges. It MUST
validate the action against the still-active local
primary-button press as specified above. If the gesture is
missing, expired or mismatched, it MUST refuse capture. The
pairing is consumed by that Begin and MUST NOT be reused for
another interaction.
MWS_WINDOW_INTERACTION_BEGIN (220), Server -> Portal
Requests temporary native input capture for a Session-owned
menu Move or Resize, or an Application-initiated move or resize
within a desktop Session. The payload is four network-order
unsigned 32-bit fields: window_id, token, mode and edges.
window_id and token MUST be nonzero. mode is Move (1) or
Resize (2). edges is zero for Move; Resize uses one edge or
two adjacent edges from MWS_WINDOW_ACTION. The Server MUST
authorise the target Window and the initiating authority before
capture: the current delegated renderer for a menu interaction,
or the owning Application for an Application drag. A token
identifies one interaction within the current attachment and
MUST NOT be reused there.
MWS_WINDOW_INTERACTION_STATUS (221), Portal -> Server
Reports native capture acquired (1), refused (2) or lost (3).
The 28-octet payload contains unsigned 32-bit window_id, token
and status, then signed 32-bit root_x, root_y, window_x and
window_y, all in network order. Acquired reports the observed
pointer position and target content origin in Session-desktop
coordinates. These are native observations, not placement
authority. Refused and Lost MUST zero all four coordinates.
An unsupported or unavailable native capture MUST be refused
without changing Window geometry. Input begins only after
Acquired. Loss ends the interaction at its last accepted
geometry; only explicit Escape restores its original geometry.
MWS_WINDOW_INTERACTION_END (222), Server -> Portal
Ends capture for the unsigned 32-bit window_id and token in
its eight-octet network-order payload. The Portal MUST release
its native capture and MUST consume any pending release and
associated text belonging to an interaction-ending key or
button before restoring ordinary Application input delivery.
MWS_WINDOW_INTERACTION_INPUT (223), Portal -> Server
Reports captured input in a 24-octet payload of unsigned
32-bit window_id, token, kind and code, followed by signed
32-bit root_x and root_y, all in network order. kind is motion
(1), button press (2), button release (3), key press (4), or
key release (5). code is zero for motion, a pointer button in
1..32 for button transitions, or a nonzero USB HID keyboard
page 0x07 usage in 1..65535 for keys. Coordinates report the
current pointer position within the Session desktop. Keys
from other HID pages are suppressed locally during capture.
All four Messages use reliable ordered delivery on Control. The
Portal sends Status before any corresponding Input. The Server
ignores stale tokens and MUST NOT apply input received before
capture admission or after termination. Interaction input MUST
NOT also reach an Application. Ordinary Input-plane events
cannot substitute for this captured conversation. Only the
Server may send Begin or End; only its attached Portal may send
Status or Input. The Server retains geometry authority
throughout and publishes decisions using MWS_CONFIGURE_WINDOW.
Capture admission is not completion of a Move or Resize. For an
Application drag, captured pointer motion adjusts geometry
subject to Window constraints. Primary-button release accepts
the current geometry and ends the interaction. Enter also
accepts; Escape restores the geometry retained when the drag
began. Withdrawal of the Window or initiating authority,
attachment loss and detachment terminate the interaction and
release capture, retaining the last accepted geometry rather
than restoring it. No capture state or Messages are retained
for replay or resume.
MWS_DECORATION_STATE (231), Server -> Portal, sets authoritative
native content presentation independently of renderer pixels.
It uses the 64-octet decoration prefix above, with nonzero
window_id, flags bit 2 (mask 4) meaning shaded, and no body.
All other flags and every other prefix field MUST be zero.
A clear flags field explicitly removes shading. Only the
Server may send this Message; it MUST NOT accept a renderer or
Application as an authority for this presentation state.
A Portal retains the decision for that Window and applies it
only when a usable frame with a nonzero top margin exists. A
shaded Window presents only its title strip, retaining full
frame pixels, content extent, Window mapping, focus and
keyboard routing. Content cannot receive pointer input while
shaded. Ordinary owner-relative popup descendants are hidden
while their owner is shaded; their identities and map requests
survive, and eligibility is reconsidered on unshade.
Desktop-relative popups remain independently positioned.
Clearing shading restores the retained full presentation; it
does not require a new Render picture or content configure.
Renderer frame flags confer no shading authority.
The Server MUST clear this presentation state when the renderer
delegation is revoked. A new Window starts unshaded. When
reconstructing a retained Window for a new Portal, the Server
MUST announce that Window before replaying its current
decoration state and supplying any current retained frame.
These Messages form part of step 3 of Section 5.2.2.1, before
MWS_SESSION_RESUME_COMPLETE, rather than following that commit
boundary. The Portal MUST NOT reuse presentation state from a
previous attachment. The Server MUST validate the current
renderer action and keep the renderer description consistent
with its own policy. These additions and the renumbered Desktop
delegation opcodes are incompatible with earlier working
revisions. Peers MUST establish support for this revision
during Session admission under Section 5.2.1 before using the
conversation.
5.2.3.3. Desktop Task Model
These Messages use reliable, ordered Control delivery. Their fields
are in network byte order and their Window identities remain subject
to Section 5.2.3.1.
MWS_TASK_MODEL_READY (224), desktop adapter -> Server, registers
the adapter using its own unmapped Window. The twenty-octet
payload contains its non-zero window_id, a flags field, and
three zero fields. Bit 2 (mask 4) opts in to MWS_WINDOW_ICON
updates for task entries; an adapter that leaves it clear MUST
NOT receive those updates. The Server MUST verify Application
ownership and MUST reject a competing registration while the
adapter exists. The Application MUST own the live desktop, or
hold an active Task-adapter delegation for this exact
registration Window under Section 5.2.3.4. The registration
Window MUST remain unmapped for the registration lifetime.
Revoking the delegation also revokes the registration, task
descriptions and task-action authority.
Payload format (exactly 20 octets):
window_id 4-octet unsigned integer
flags 4-octet unsigned integer
reserved_1 4-octet unsigned integer (zero)
reserved_2 4-octet unsigned integer (zero)
reserved_3 4-octet unsigned integer (zero)
MWS_TASK_DESCRIPTION (225), Server -> desktop adapter, publishes
one ordinary top-level task. Its fixed prefix contains
window_id, flags, role, title length, and application-ID length
as five unsigned 32-bit fields. The unterminated UTF-8 title
follows the prefix and the unterminated UTF-8 application ID
follows the title. Bit 0 (mask 1) means mapped, bit 1 (mask 2)
means active, and bit 3 (mask 8) means minimised. Clearing
mapped removes an existing task. Minimised MUST NOT be set
unless mapped is also set; minimised and active MUST NOT both
be set. The Server MUST NOT describe desktop, panel, popup,
transient, passive, or internal Windows as independent tasks.
The two strings MUST each contain no more than 255 octets and
MUST be valid UTF-8 without embedded NUL octets. All unassigned
flag bits MUST be zero. Active MUST NOT be set unless mapped is
also set.
Payload format:
window_id 4-octet unsigned integer
flags 4-octet unsigned integer
role 4-octet unsigned integer
title_len 4-octet unsigned integer
application_id_len 4-octet unsigned integer
title title_len octets
application_id application_id_len octets
The payload length is exactly 20 + title_len +
application_id_len octets. role uses the Window-role values
defined for MWS_WINDOW_RELATION in Section 5.2.3.
MWS_TASK_ACTION (226), desktop adapter -> Server, requests an
action on a published task. Its eight-octet payload contains a
non-zero window_id and operation as unsigned 32-bit fields.
Operation 1 activates the Window, 2 requests ordinary close,
and 3 toggles minimisation. The Server MUST accept this Message
only from the registered adapter in the same Session and MUST
reject unknown, removed, or non-top-level Windows. Minimisation
affects Portal visibility while preserving the task entry.
Payload format (exactly 8 octets):
window_id 4-octet unsigned integer
operation 4-octet unsigned integer
5.2.3.4. Desktop Component Delegation
A desktop may consist of several Applications. Window ownership
remains with each Application; a desktop owner MAY delegate only the
Panel and Task-adapter responsibilities below. These Messages use
reliable, ordered Control delivery on authenticated client channels;
they are not exchanged with the Portal.
MWS_DESKTOP_OFFER (232), desktop owner -> Server
MWS_DESKTOP_ACCEPT (233), component owner -> Server
MWS_DESKTOP_REVOKE (234), either endpoint owner -> Server
MWS_DESKTOP_STATE (235), Server -> endpoint Applications
These distinct Message types share the following payload format
(exactly 24 octets):
window_id 4-octet unsigned integer
desktop_id 4-octet unsigned integer
rights 4-octet unsigned integer
state 4-octet unsigned integer
offer_id 8-octet unsigned integer
All multi-octet fields are in network byte order. window_id
occupies octets 0--3 for routing and identifies the component
Window owned by the component Application. OFFER and ACCEPT
require both Windows to be live, with desktop_id identifying a
distinct role 3 Window owned by another Application in the same
Session. Revoked STATE may name an endpoint already removed.
Knowing these identifiers, sharing a UID, process ancestry or
inherited environment MUST NOT establish delegation authority.
rights is a nonempty bit mask. Bit 0 (mask 1) permits only
window_id to acquire a role 4 relationship to desktop_id. Bit 1
(mask 2) permits only window_id to register as the Task adapter
under Section 5.2.3.3. All other bits MUST be zero. Neither
right permits subdelegation, ownership transfer, input
interception, reserved screen space, or operations beyond its
defined role. Multiple component Windows require separate
offers. Existing same-Application desktop roles require no
delegation exchange.
MWS_DESKTOP_OFFER MUST originate from the Application owning
desktop_id, with state and offer_id zero. The Server validates
both live Windows within its Session and assigns a nonzero
offer_id which MUST NOT be reused during that Session. There
MUST NOT be more than one outstanding or active offer for a
component Window. Repeating an otherwise identical OFFER
returns the retained offer and state, without allocating a new
identity. Changing a pending or active offer requires
revocation followed by a new OFFER. A pending offer grants no
authority. Desktop registration and selection remain subject to
Server policy; this exchange does not establish the initial
desktop authority.
MWS_DESKTOP_ACCEPT MUST originate from the Application owning
window_id. It MUST exactly match a pending offer's identifiers,
rights and nonzero offer_id, with state zero. The Server then
makes those rights active. An identical repeated ACCEPT for an
already active offer is idempotent. An expired or superseded
offer MUST NOT be accepted. Consent to one offer cannot be
applied to a later offer with the same Window identifiers.
MWS_DESKTOP_REVOKE MAY originate from either endpoint's owning
Application. It MUST name the exact offer with state zero. It
withdraws pending or active rights. Repeating the exact REVOKE
is idempotent and MAY retry incomplete cleanup or notification;
it MUST NOT withdraw a later, independently authorised role.
The surviving component owner MAY revoke its retained offer
after the Desktop loses its role or disappears. No other
Application may accept or revoke the offer. The Server MUST
also revoke when either endpoint Window is removed, either
Application retires, or desktop_id ceases to have role 3.
Revocation cannot be undone by an old ACCEPT. A new offer
requires fresh consent.
MWS_DESKTOP_STATE originates only from the Server. It carries
the exact offer and state 1 (pending), 2 (active), or 3
(revoked). The Server sends each transition to both endpoint
Applications while their Channels remain live. Requests MUST
have state zero; STATE MUST have nonzero offer_id. All other
state values are invalid. A submitted request is not
confirmation: only the Server's STATE reports the accepted
transition. Peer-originated STATE MUST be rejected.
The Server MUST validate sender provenance and the complete
request before changing authority. Revocation MUST withdraw
authority before attempting fallible peer notifications. It
MUST end any Task registration derived from that active grant
and unmap and clear the delegated Panel relationship without
transferring or destroying the component Window. Native cleanup
and notification failure MUST NOT reinstate authority. Until
retained Panel withdrawal has completed, the Server MUST reject
remapping or replacing that component's relationship, so a
cleanup retry cannot overwrite a later independent Window role.
Destruction remains permitted. Application-owned transient and
popup descendants retain their ordinary ownership and lifetime
rules. Session destruction releases every offer.
Servers without these Messages cannot support cross-Application
delegation. An Application MUST NOT interpret unsupported-
message rejection or lack of STATE as permission to proceed.
Existing same-Application relationships and task Messages
retain their wire layouts; no implicit cross-Application
fallback is defined.
5.3. Rendering Messages (300-399)
Portal-association rendering Messages are delivered on SCTP stream 1.
Client-channel rendering Messages are exchanged between the Library
and the Server. Each is validated against the Window and resources
belonging to the addressed Session.
MWS_RENDER_PRESENT (type=300) -- Server -> Portal
(Portal association)
Presents a rendering update on the Portal. The server sends
portal-ready rendering data for the addressed Window.
Payload format:
window_id 4-octet unsigned integer
x 4-octet signed integer
y 4-octet signed integer
width 4-octet unsigned integer
height 4-octet unsigned integer
damage_x 4-octet unsigned integer
damage_y 4-octet unsigned integer
damage_width 4-octet unsigned integer
damage_height 4-octet unsigned integer
buffer_size 4-octet unsigned integer
encoding 4-octet unsigned integer
data_size 4-octet unsigned integer
generation 8-octet unsigned integer
media_time 8-octet unsigned integer
data data_size octets
window_id, width, and height MUST be non-zero. x and y are the
Window position in compositor coordinates. buffer_size MAY be
zero, in which case the Message changes no pixel content and
every damage field and data_size MUST be zero. Otherwise,
damage_width and damage_height MUST be non-zero and the damage
rectangle MUST lie wholly within width and height. encoding is
0 for uncompressed BGRA8888 data or 1 for a Zstandard frame
[RFC8878] containing exactly buffer_size decompressed octets.
Compressed frames MUST NOT require an external dictionary.
data_size is the number of encoded data octets following the
fixed header. A sender SHOULD use encoding 1 only when doing so
reduces the total Message size. A receiver MUST reject an
unknown encoding, malformed compressed data, or data which does
not decode to exactly buffer_size octets. generation is the
shared Session presentation sequence described for
MWS_SESSION_STATUS. It increases across MWS_RENDER_PRESENT and
MWS_VIDEO_DATA actually transmitted on the association,
irrespective of the addressed Window or presentation plane. A
queued presentation discarded before transmission consumes no
sequence. media_time is the non-zero Workstation Session
monotonic time, in nanoseconds, at which the Application
submitted the image for presentation. It is captured before
readback, compression, pacing, or network transmission and is
interpreted as described in Section 5.6.1.
For a geometry-only update, encoding MUST be zero; media_time
records the Workstation time of that update. A non-zero pixel
buffer is tightly packed BGRA8888 in VK_FORMAT_B8G8R8A8_UNORM
byte order. Each row contains exactly damage_width * 4 octets
and buffer_size MUST equal damage_width * damage_height * 4.
For encoding 0, data_size MUST equal buffer_size. The payload
length MUST equal 64 + data_size. A sender whose source image
has a larger row stride MUST repack it before constructing this
Message.
MWS_RENDER_SYNC (type=301) -- Server -> Portal
(Portal association)
Requests synchronisation of rendering state on the portal. The
server uses this command to ensure that the portal has retired
all preceding MWS_RENDER_PRESENT work for the Window before
processing later Render operations for it. This is a
Portal-local barrier and has no reply; the Server observes
cumulative progress through MWS_SESSION_STATUS. Control
processing MUST remain responsive while this Render barrier is
pending.
Payload format:
window_id 4-octet unsigned integer
MWS_RENDER_DESTROY (type=302) -- Server -> Portal
(Portal association)
Requests destruction of rendering resources associated with
a window or pipeline on the portal. The portal releases any
corresponding portal-side rendering state when it is safe to do
so.
Payload format:
window_id 4-octet unsigned integer
MWS_RENDER_UPLOAD (type=303) -- Library -> Server
(client channel)
Provides new rendering content for a window's surface. The
Library translates completed Client rendering into a bounded
update to the Window's image data or GPU-resident resources on
the Server. This Message does not cross the Portal association.
Payload format:
window_id 4-octet unsigned integer
width 4-octet unsigned integer
height 4-octet unsigned integer
stride 4-octet unsigned integer
buffer_size 4-octet unsigned integer
media_time 8-octet unsigned integer
pixels buffer_size octets
Pixels are BGRA8888 in VK_FORMAT_B8G8R8A8_UNORM byte order.
window_id, width, height, stride, buffer_size, and media_time
MUST be non-zero. stride MUST be at least width * 4.
buffer_size MUST equal stride * height, and the payload length
MUST equal 28 + buffer_size. media_time has the same meaning as
in MWS_RENDER_PRESENT and MUST be preserved by the Server.
Arithmetic validation MUST detect overflow.
MWS_RENDER_DAMAGE (type=304) -- Library -> Server
(client channel)
Replaces one rectangular region of the Window's retained
canonical image. A complete MWS_RENDER_UPLOAD MUST establish
that image before the first MWS_RENDER_DAMAGE. The update and
its rectangle are one atomic Message; damage never describes a
later Message.
Payload format:
window_id 4-octet unsigned integer
surface_width 4-octet unsigned integer
surface_height 4-octet unsigned integer
damage_x 4-octet unsigned integer
damage_y 4-octet unsigned integer
damage_width 4-octet unsigned integer
damage_height 4-octet unsigned integer
stride 4-octet unsigned integer
buffer_size 4-octet unsigned integer
media_time 8-octet unsigned integer
pixels buffer_size octets
Every dimension, stride, buffer_size, and media_time MUST be
non-zero. The damage rectangle MUST lie wholly within the
surface. Pixels are tightly packed BGRA8888 in
VK_FORMAT_B8G8R8A8_UNORM byte order; stride MUST equal
damage_width * 4, buffer_size MUST equal stride *
damage_height, and the payload length MUST equal 44 +
buffer_size. The surface dimensions MUST equal those of the
retained image. A receiver which has no retained image, or
whose retained extent differs, MUST reject the update without
changing its retained content.
MWS_RENDER_FENCE (type=305) -- Library <-> Server
(client channel)
Reserved for synchronising rendering progress. Its payload and
semantics are not defined by this version. A sender MUST NOT
emit this Message until a later specification defines it.
The BGRA8888 pixel representations in MWS_RENDER_PRESENT,
MWS_RENDER_UPLOAD, and MWS_RENDER_DAMAGE use premultiplied alpha for
translucent presentation: each colour component is already multiplied
by alpha, and the Portal MUST NOT multiply it a second time. A Portal
may present a Window as opaque where its role or native presentation
environment does not support transparency; alpha is then ignored.
This convention is independent of the straight-alpha Window icon
representation.
A partial update MUST NOT be applied without a retained complete
image of the same extent. The first pixel update after creation,
resize, resource destruction, or resume MUST cover the complete
Window image. Superseding an update is permitted only when later
retained content includes its effects. In particular, dropping an
independent damage rectangle must not erase changes needed by a later
partial update.
A Portal MUST handle cross-stream arrival without assuming that a
Window creation on Stream 0 is processed before its Render data. It
may retain early data within its limits until creation is processed.
A destroyed Window's in-flight Render data is discarded and retired.
Window identifiers MUST NOT be reused on the same Session attachment.
Before posting Render for a newly created Window, the Server MUST
admit its MWS_WINDOW_CREATED announcement to ordered Control
delivery, without waiting for a Portal acknowledgement. The
announcement and dependent Render MUST use the same Server monotonic
clock domain. A Portal retaining early Render MUST use the
Server-originated Window lifecycle frontier defined in Section 5.4. A
matching announcement admits retained updates with equal or later
postmarks, in their original Render order. Older updates are
discarded. Strictly later lifecycle progress discards retained
updates for still unknown Windows; equality alone does not establish
that Control has caught up. Retention MUST remain bounded
independently of peer postmarks and MUST NOT create a Window or grant
authority. All retained data MUST be released on attachment teardown.
Admission counts as receipt once; retirement follows presentation or
discard, including rejection of invalid compressed data during
replay. Replay MUST preserve the original local receipt time used to
recover the shared media timeline.
Every multi-octet field above is in network byte order. Every defined
rendering payload begins with a non-zero window_id. A recipient MUST
reject an incorrect payload length, inconsistent geometry or buffer
size, arithmetic overflow, or a Window outside the permitted Session.
5.4. Input Plane (400-499) -- Stream 2
SCTP Stream 2 carries Input Plane Messages and MWS_FOCUS_WINDOW as
specified in Section 4.7. Portal-to-Server Messages describe
Seat-scoped events without coupling the protocol to a particular
Portal window system. Client-originated Messages request
Window-scoped input behaviour through the authoritative Server. This
version defines pointer focus, ordinary pointer motion,
pointer-button transitions, physical-key transitions, committed text
input, and pointer modes. Other device classes retain the common
event envelope but require later definitions of their event data.
Control and Input progress independently. Before posting a
Server-to-Portal Input decision concerning a newly created Window,
the Server MUST admit that Window's MWS_WINDOW_CREATED announcement
to ordered Control delivery. It MUST NOT wait for a Portal
acknowledgement. The announcement and dependent decision MUST use
the same established monotonic clock domain.
MWS_WINDOW_CREATED and MWS_WINDOW_DESTROYED on Control carry their
Server origin's postmark. A Portal may track the greatest such
postmark received on its current Session attachment as Control
progress. It MUST NOT advance that frontier using an arbitrary
forwarded Message whose originating clock domain has not been
established as the same Server clock. Receipt on Control alone does
not establish that provenance.
After validating a Server-originated MWS_FOCUS_WINDOW or
MWS_INPUT_POINTER_MODE, a Portal receiving it for an unannounced
Window MUST defer native action. If its postmark is greater than or
equal to the observed Control frontier, or no frontier has been
established, the Portal MUST retain it within its security limits.
If the frontier is strictly greater and the Window remains unknown,
the Portal MUST discard the decision without terminating the
association. Equality does not establish that Control has caught up.
On receiving the matching MWS_WINDOW_CREATED, the Portal MUST apply
retained decisions whose postmarks are greater than or equal to the
announcement's postmark, in their retained Input order. Older
retained decisions for that identifier are discarded. Equality is
accepted here because the announcement establishes the matching
Window and identifiers cannot be reused on the attachment; it does
not establish an ordering between equal clock samples. Native action
MUST wait until native creation and its required metadata are ready.
A strictly later Control frontier retires retained decisions for
Windows that are still unknown. Destruction retires pending decisions
for its Window; a superseding focus decision MUST NOT restore an
earlier retained focus. A Portal MUST bound retained storage
independently of peer-supplied postmarks, clear it on attachment
teardown, and continue Control processing while decisions are
deferred. Retention never creates a Window or grants authority.
Server validation of unknown or unauthorised Portal-to-Server
references remains unchanged. A focus-loss decision for an absent
Window may be consumed immediately as specified in Section 5.2.3.
MWS_INPUT_EVENT (type=400) -- Portal -> Server
Delivers an input event from an authorised Seat.
Payload envelope:
window_id 4-octet unsigned integer
seat_id 4-octet unsigned integer
device_id 4-octet unsigned integer
sequence 4-octet unsigned integer
timestamp_ms 4-octet unsigned integer
event_type 2-octet unsigned integer
event_data_len 2-octet unsigned integer
event_data event_data_len octets
window_id identifies the destination Window within the Session.
seat_id identifies the Seat within the authenticated Session.
device_id identifies an input device attached to that Seat.
None of these Portal-provided identifiers confers authority:
the server MUST resolve all three within the Session bound to
the association and MUST reject an unauthorised or unknown
value.
sequence is scoped to the Portal association. It MUST begin at
a non-zero value, increase for every emitted Input event, and
skip zero when it wraps. Ordering uses the 32-bit serial-number
arithmetic of [RFC1982]; an ambiguous half-range difference is
invalid. The receiver MUST reject a duplicate or older
sequence. timestamp_ms is the low 32 bits of a monotonic
Portal-local millisecond clock. It establishes timing between
events from that Portal and is not wall-clock time.
event_type selects the interpretation of event_data. The
payload length MUST equal 24 + event_data_len. Unknown event
types MUST be rejected unless a negotiated extension defines
them.
MWS_INPUT_ACK (type=401) -- Server -> Portal
Acknowledges an input event when its event class requires an
explicit acknowledgement. This version defines no event
requiring an acknowledgement; a sender MUST NOT emit
MWS_INPUT_ACK.
MWS_INPUT_POINTER_MODE (type=402) -- Client -> Server -> Portal
Requests pointer behaviour for a Window owned by the Client.
Payload:
window_id 4-octet unsigned integer
modes 4-octet unsigned integer
window_id identifies the Window within the Session. The server
MUST verify that the sending Client owns that Window before
forwarding the Message. A Portal MUST NOT treat this request as
authority over another Window or over the Portal desktop.
modes is a bit mask. Bit zero requests relative pointer motion,
bit one requests confinement to the Window, and bit two
requests that the native pointer image be hidden while the
Window has focus. Bits three through 31 MUST be zero. A zero
value releases all requested pointer behaviour.
Pointer behaviour is Window-scoped and active only while that
Window has focus. The Portal MUST release native confinement
and restore its pointer image when focus is lost, the Window is
unmapped or destroyed, or the Session ends. Portal policy and
an unconditional Portal-local escape mechanism take precedence
over a Client request.
seat_id MUST be non-zero and unique among the live Seats in its
Session. device_id MUST be non-zero and unique among the live input
devices attached to that Seat. Both identifiers are opaque protocol
values except for the following base assignments. After Session
establishment, the Server and Portal use Seat 1, logical pointer
device 1, and logical keyboard/text device 2. These are
Session-scoped logical devices, not physical hardware identifiers.
Pointer events MUST use device 1; keyboard and TEXT events MUST use
device 2. A Portal may aggregate native devices into those logical
devices. This revision defines no wire exchange to create additional
Seats or devices; such identifiers MUST NOT be used without an
applicable extension.
On detach, association loss, or resume, the Server MUST clear held
keys, buttons, and focus from the old attachment. The resumed Portal
starts with fresh device state and sequence numbering. Input Messages
in this revision MUST use reliable, ordered delivery on Stream 2.
Coalescing is permitted only before transmission and only as
specified below. The Server forwards accepted events on the owning
Application's client channel; pointer-mode requests travel Library ->
Server -> Portal.
The base Input Plane and any future extensions MUST satisfy the
following requirements where applicable:
* An extension adding device discovery MUST describe capabilities,
identity, attachment to a Seat, hot-plug, and removal without
coupling MWS to a particular Portal operating system or input
API.
* The workstation MUST remain authoritative for focus, routing,
grabs, policy, and the interpretation of which Client and Window
may receive an event.
* Key transitions, button transitions, and other state-changing
events MUST be delivered reliably and in order. They MUST NOT be
discarded, coalesced, or reordered across one another.
* Superseded pointer or tablet motion MAY be coalesced only when
doing so cannot cross or alter the meaning of an intervening
state-changing event. Both relative and absolute motion MUST be
representable.
* Events MUST carry sufficient sequencing and timing information
to preserve their intended order and identify stale or invalid
device state. Event batching MUST NOT change event semantics.
* Physical key events MUST remain distinguishable from text entry
and input-method composition. The protocol MUST NOT assume that
a keyboard layout or input method is shared by both endpoints.
* Device loss or Portal disconnection MUST resolve held keys,
buttons, touches, and similar state without leaving input stuck
in the workstation Session.
* The vocabulary MUST be extensible to touch, tablet pressure and
tilt, accessibility devices, and control surfaces without
weakening the Session and Seat authority rules.
* Where a device requires feedback, such as keyboard indicator or
haptic state, the workstation-to-Portal direction MUST be
represented explicitly and subject to the same Seat scoping.
5.4.1. Pointer Motion Events
Pointer events use the following event_type values:
1 POINTER_MOTION
2 BUTTON_PRESS
3 BUTTON_RELEASE
7 POINTER_ENTER
8 POINTER_LEAVE
Each carries this 20-octet event_data:
x 4-octet unsigned integer
y 4-octet unsigned integer
delta_x 2-octet signed integer
delta_y 2-octet signed integer
buttons 4-octet unsigned integer
button 2-octet unsigned integer
reserved 2-octet unsigned integer
x and y are unsigned Window-content-local pixel coordinates. A native
coordinate below zero MUST be encoded as zero on that axis. A
non-negative coordinate beyond the content extent retains its value;
it is not clamped to the last content pixel. Coordinates alone
therefore do not establish that the pointer is inside the Window.
POINTER_ENTER and POINTER_LEAVE report the native pointer-focus
transition, including when the encoded position lies on or beyond a
content boundary.
delta_x and delta_y are signed changes since the preceding pointer
event for this device. A zero delta reports no relative movement.
Encoding a negative absolute coordinate as zero does not change the
signed representation of relative movement.
buttons is the complete state after this event. Bit zero represents
primary button 1, bit one middle button 2, and bit two secondary
button 3; subsequent bits represent additional pointer buttons in
ascending order. For BUTTON_PRESS and BUTTON_RELEASE, button
identifies the changed button and MUST be in the range 1 through 32.
For POINTER_MOTION, POINTER_ENTER, and POINTER_LEAVE, button MUST be
zero. reserved MUST be zero.
POINTER_ENTER reports that the pointer entered the Window content and
POINTER_LEAVE reports that it left. These events are distinct from
keyboard focus and MUST reflect the Portal's native pointer-focus
transitions. They carry the pointer position and complete button
state at the transition.
Button and pointer-focus transitions MUST be delivered reliably and
in sequence order. POINTER_MOTION may be coalesced only with later
motion for the same Seat, device, and Window, and only when no button
or other state-changing event intervenes. The resulting event MUST
retain the newest absolute position and button state, and the sum of
relative deltas. If that sum does not fit the signed fields, the
events MUST remain separate. This version requires no MWS_INPUT_ACK
for pointer events.
5.4.2. Keyboard Events
Keyboard events use the following event_type values:
4 KEY_PRESS
5 KEY_RELEASE
Each carries this 8-octet event_data:
usage 4-octet unsigned integer
modifiers 4-octet unsigned integer
usage identifies the physical control using the extended Usage
encoding defined by the USB HID Usage Tables [HUT17]. The most
significant 16 bits contain the Usage Page and the least significant
16 bits contain the Usage ID. Both parts MUST be non-zero, and their
combination MUST identify an assigned Usage in [HUT17]. This single
namespace includes the Keyboard/Keypad Page, the Consumer Page used
by media controls, and the other controls defined by that
specification; MWS does not maintain a separate key registry.
KEY_PRESS and KEY_RELEASE describe physical transitions and MUST
remain distinct from text entry or input-method composition. A Portal
MUST map its native input identifier to the corresponding HID Usage
without assuming that the Portal and workstation share a keyboard
layout.
modifiers contains the complete modifier state accompanying the
transition. Bits zero through seven correspond directly to the
modifier byte in a USB HID keyboard report: Left Control, Left Shift,
Left Alt, Left GUI, Right Control, Right Shift, Right Alt, and Right
GUI, respectively. In keyboard layouts which define an AltGr
modifier, Right Alt commonly supplies that function.
Bits eight, nine and ten report the Portal's Caps Lock, Num Lock and
Scroll Lock state, respectively: a set bit means that lock is active.
These three bits MUST describe the native lock state immediately
before the reported key transition. In particular, a lock key press
reports its previous state, so that applying the transition does not
toggle an already updated state a second time. The Portal MUST use
its native keyboard state, including locks changed while another
Window had focus; it MUST NOT infer the snapshot solely from key
transitions previously sent to the Session. Bits eleven through 31
MUST be zero.
The receiving endpoint MUST honour the lock snapshot when
interpreting the transition. This permits an Application to recover
the current state after focus changes or Session resumption without
requiring the Portal and workstation to have started with matching
locks.
Key transitions MUST be delivered reliably and in sequence order.
They MUST NOT be discarded, coalesced, or reordered. This version
requires no MWS_INPUT_ACK for keyboard events.
5.4.3. Text Input Events
Text input uses this event_type value:
6 TEXT
event_data contains between 1 and 31 octets of well-formed UTF-8
text. It MUST NOT contain U+0000. A Portal MUST divide longer
committed text into consecutive TEXT events at UTF-8 character
boundaries.
TEXT reports text committed by the Portal's active keyboard layout or
input method. It is distinct from the physical KEY_PRESS and
KEY_RELEASE events which may have contributed to that text. A Portal
MUST perform layout selection, dead-key handling, compose processing,
and input-method composition locally; the server MUST NOT infer text
from HID Usages or assume that both endpoints share a keyboard
layout.
device_id identifies the keyboard or other text-input device
associated with the commit. TEXT events MUST be delivered reliably
and in sequence order. They MUST NOT be discarded, coalesced, or
reordered.
5.5. Video Presentation (500-599)
The Video Plane carries Server-selected fallback for ordinary Render
content when Transport cannot reasonably sustain its delivery. It
also permits Application-supplied encoded content through the
Library, subject to Server authorisation, negotiation and resource
limits; this use does not require Transport pressure or prior
decoding into Render pixels. Render remains the default for ordinary
content. This revision defines fixed-size negotiated Video Window
presentation.
A producer is either the Library, supplying encoded Application
content, or the Server, encoding the contents of a Window it owns.
Library-produced Messages cross the client channel to the Server and
then the Portal association. Server-produced Messages cross only the
Portal association. FORMATS replies and STATUS return to the
producer: the Server consumes replies to its own exchanges and MUST
NOT deliver them to the Library. Every payload starts with a non-zero
window_id and stream_id, each an unsigned 32-bit integer. window_id
identifies a Window in the attached Session; the Server MUST
authorise its owning Application before forwarding any client-channel
request. A Portal cannot grant Application authority by supplying a
Window identifier.
The Server MUST arbitrate Library and Server production so that they
cannot create concurrent exchanges for the same Window. Both
producers share the same Window-scoped stream identifier space and
lifecycle rules.
stream_id identifies one playback lifetime within that Window. IDs
MUST increase strictly across FORMATS requests and MUST NOT be
reused. No further negotiation may start on that Window after ID
exhaustion. At most one negotiation or stream may be live for a
Window, without imposing a Session-wide limit on the number of
Windows with streams.
MWS_VIDEO_FORMATS (500) -- Producer -> Portal through Server;
reply reverse
Reliable ordered Control. A 12-octet prefix followed by count
unsigned 32-bit format identifiers:
window_id 4-octet unsigned integer
stream_id 4-octet unsigned integer
count 4-octet unsigned integer
formats count consecutive 4-octet unsigned integers
Negotiation occurs only when Video is wanted, not during the
Session handshake. The request lists formats available from the
producer; the reply lists formats available at the Portal in
preference order. Both lists may contain zero, one or many
entries. Their complete extent MUST match count exactly and
remains subject to the peer's logical-payload limit. Zero and
duplicate identifiers are invalid. Unknown non-zero identifiers
are valid but unsupported unless understood by the receiver.
The reply MUST use the request's Window and stream identifiers.
A request consumes a fresh stream_id; a subsequent OPEN uses
that same identifier after the matching reply. Another request
MUST NOT replace a pending negotiation or accepted stream.
Empty lists or no common entry mean Video is unavailable for
this attempt; ordinary Render remains available. A new attempt
uses a new stream_id. Late replies MUST NOT revive retired
attempts.
The producer selects a format present in both lists. Portal
preference order informs this choice but does not prescribe a
universal codec ranking. The Server MUST enforce membership in
the producer's advertised list; the Portal MUST enforce
membership in its own advertised list. Advertisement is not
resource reservation: OPEN may still be rejected. A FORMATS
attempt may also terminate with STATUS REJECTED and reason
RESOURCE or STATE before OPEN; no format reply or decoder
acceptance is then implied. Negotiation state is scoped to this
Window lifetime and is not carried across detach or Portal
replacement.
Format 1 is HEVC Main [HEVC], progressive 8-bit 4:2:0 without
B pictures, carried as Annex-B access units with exactly one
output picture per unit. The first unit MUST contain an IDR
picture and the VPS, SPS and PPS needed to decode without
external state. Subsequent units may depend on preceding
pictures. No container is carried.
Format 2 is H.264 Main [AVC], progressive 8-bit 4:2:0, carried
as Annex-B access units with exactly one output picture per
unit. Only I and P pictures are permitted; B pictures and
display reordering are not permitted. The first unit MUST
contain an IDR picture and the SPS and PPS needed to decode
without external state. Subsequent units may depend on
preceding pictures. No container is carried. Additional format
identifiers MUST define equally precise interoperable
representations.
MWS_VIDEO_OPEN (501) -- Producer -> Portal through Server
Reliable ordered Control, after Window creation. A Server may
open Video after ordinary Render presentation for that Window,
subject to the transition ordering below. Exactly 28 octets:
window_id 4-octet unsigned integer
stream_id 4-octet unsigned integer
format 4-octet unsigned integer
width 4-octet unsigned integer
height 4-octet unsigned integer
fps_numerator 4-octet unsigned integer
fps_denominator 4-octet unsigned integer
Dimensions and both rate fields MUST be non-zero. The stream
fixes the decoded image size and nominal frame rate. format
MUST identify an entry present in both matching FORMATS lists.
The receiver MUST either accept these exact parameters or
reject the request. No implicit resizing or codec substitution
is permitted. The receiver uses hardware decoding for the
selected format; an unavailable profile requires rejection.
OPEN acceptance establishes that the Window and decoder exist
before DATA.
MWS_VIDEO_STATUS (502) -- Portal -> Producer through Server
Reliable ordered Control. Exactly 24 octets:
window_id 4-octet unsigned integer
stream_id 4-octet unsigned integer
sequence 8-octet unsigned integer
state 4-octet unsigned integer
reason 4-octet unsigned integer
States are ACCEPTED (1), RETIRED (2), CLOSED (3), REJECTED (4)
and FAILED (5). REJECTED may terminate negotiation before OPEN
or refuse OPEN. ACCEPTED and REJECTED require sequence zero.
RETIRED is optional cumulative stream progress, not a
per-picture acknowledgement or permission to send another DATA.
Its non-zero sequence confirms consumption through that access
unit and successful native presentation submission or
deliberate discard, not merely decoder enqueue. Session-wide
delivery and capacity progress is reported by
MWS_SESSION_STATUS; producers MUST NOT depend on receiving
RETIRED for each access unit. Physical compositor display
completion is not implied; codec reference pictures and the
last independent display image may remain retained. CLOSED
reports the final retired sequence, which may be zero for an
empty stream. FAILED terminates an accepted stream and reports
the last retired sequence.
reason is NONE (0), UNSUPPORTED (1), RESOURCE (2), DECODE (3)
or STATE (4). REJECTED and FAILED require a non-zero reason;
all other states require NONE. These are portable wire reasons,
not host errno values. Unsupported parameters, unavailable
decoder resources and malformed encoded content MUST produce a
controlled stream-local failure, not silently substitute data.
MWS_VIDEO_DATA (503) -- Producer -> Portal through Server
Reliable ordered Video (Stream 3). Fixed prefix of 32 octets:
window_id 4-octet unsigned integer
stream_id 4-octet unsigned integer
sequence 8-octet unsigned integer
media_time 8-octet unsigned integer
presentation_sequence 8-octet unsigned integer
data remaining payload octets
data MUST contain one complete, non-empty encoded unit in the
representation identified by OPEN, producing exactly one output
picture. The selected format defines framing and independent
initialisation requirements.
Decoded dimensions MUST match OPEN. sequence starts at 1 and
increases by one; the stream MUST close before exhaustion.
media_time is the stream-relative time in nanoseconds, starting
at zero and increasing strictly. It is not the Session Audio
timeline and does not request Audio synchronisation. The sender
paces access units; the receiver presents accepted output when
ready rather than scheduling against a remote clock.
The Library MUST set presentation_sequence to zero on the
client channel. Before association transmission, the Server
MUST assign the next non-zero shared Session presentation
sequence. The Portal MUST account for its complete logical
Message using the same byte and presentation credit as Render.
Untransmitted work consumes no sequence; a transmitted sequence
MUST NOT be omitted from the receiver's cumulative accounting,
including stale Window work.
A sender MUST wait for ACCEPTED before DATA. It then sends
asynchronously within the Session admission envelope, without
waiting for individual picture retirement. Dependent access
units MUST NOT be discarded before decoding merely to reduce
backlog; ordinary source content may be superseded before
encoding. Each Message remains subject to the peer's
logical-payload limit. The receiver MUST validate all lengths,
decoded dimensions and allocation arithmetic before accepting
their resources. It MAY reject a stream according to its
available resources. Reliable ordered delivery and existing
Transport fragmentation preserve dependent decoder state;
partial reliability and unordered delivery MUST NOT be used.
MWS_VIDEO_CLOSE (504) -- Producer -> Portal through Server
Reliable ordered Video (Stream 3). Exactly 16 octets:
window_id 4-octet unsigned integer
stream_id 4-octet unsigned integer
final_sequence 8-octet unsigned integer
CLOSE MUST follow the last sent DATA on ordered Video;
final_sequence MUST equal that DATA sequence, or zero for an
empty accepted stream. The receiver consumes and retires all
preceding DATA before retiring decoder resources and replying
CLOSED. The sender MUST wait for CLOSED before submitting
ordinary Render content for that Window. The last displayed
image may remain until replaced. These acceptance and close
handshakes establish ordering across independent Control, Video
and Render streams.
Window destruction cancels its playback resources and pending work.
Unmapping a live Window cancels playback with FAILED and reason
STATE; remapping requires a fresh stream lifetime. Late Video traffic
for that destroyed Window or retired stream MUST be discarded without
recreating resources. A malformed Message or forbidden direction
remains subject to the ordinary protocol-error rules. A live stream
state violation MUST be rejected without acting on another stream.
Session detachment ends these playback lifetimes; attachment requires
fresh FORMATS and OPEN exchanges and an independently decodable first
access unit. Render is the default for ordinary content; the Server
may choose Video when Transport cannot sustain the required Render
delivery. Before negotiating that transition, the Server MUST stop
further Render delivery for the Window and observe retirement of its
preceding transmitted Render work through MWS_SESSION_STATUS. Unsent
Render work may be superseded. This one-time drain prevents old
Render content overtaking the new Video stream across independent
streams. If negotiation or OPEN is rejected, ordinary Render remains
available. Server production obeys the same negotiation, retirement
and closure rules as Library production. Changing the encoded extent
requires closing the old stream and negotiating a fresh lifetime.
Seeking, loss recovery and Audio synchronisation are not defined
here.
5.6. Audio Plane (600-699) -- Stream 4
The Audio Plane is intended to provide full-duplex, timestamped audio
between workstation and Portal. Playback carries audio from the
workstation to the Portal; capture carries audio from a
Portal-attached device to the workstation. Stream 4 is reserved so
that audio does not share control, rendering, input, or video
traffic.
Each logical audio stream has a 32-bit stream_id assigned by the
Server. Application-local identifiers are translated at the Server
when necessary to avoid collisions on the Portal association. A
Session MAY have zero or more playback and capture streams. An opener
proposes the stream parameters; the peer accepts or rejects them
before any data is sent.
MWS_AUDIO_PLAYBACK_OPEN (type=600) -- Server -> Portal
Proposes a playback stream and its parameters.
MWS_AUDIO_PLAYBACK_ACCEPT (type=601) -- Portal -> Server
Accepts the proposed playback stream.
MWS_AUDIO_PLAYBACK_REJECT (type=602) -- Portal -> Server
Rejects the proposed playback stream. The server MUST NOT send
playback data for the rejected stream_id.
MWS_AUDIO_PLAYBACK_DATA (type=603) -- Server -> Portal
Carries timestamped audio for an accepted playback stream.
MWS_AUDIO_PLAYBACK_CLOSE (type=604) -- Server -> Portal
Ends a playback stream and permits its resources to be
reclaimed.
MWS_AUDIO_PLAYBACK_CAPABILITIES (type=605) -- Server -> Library
Repeats the Portal playback envelope from MWS_SESSION_INFO
across the private client channel. This Message does not
traverse the network association. It lets the Library reject
unsupported playback-open requests before forwarding them to
the Server.
The payload contains minimum and maximum sample rates as two
four-octet unsigned integers, followed by a two-octet maximum
channel count and a two-octet set of sample formats. Every
field is in network byte order and has the same meaning as its
MWS_SESSION_INFO counterpart.
MWS_AUDIO_PLAYBACK_OPEN has the following payload:
Field Size Meaning
----------------- ------ ------------------------------------
stream_id 4 Non-zero proposed stream identifier
sample_rate 4 Sample frames per second
channel_count 2 Interleaved channels per frame
sample_format 2 Sample representation (see below)
frames_per_packet 4 Preferred packet duration in frames
MWS_AUDIO_PLAYBACK_ACCEPT and MWS_AUDIO_PLAYBACK_REJECT each carry
only the four-octet stream_id to which the reply applies.
MWS_AUDIO_PLAYBACK_DATA has the following fixed header followed
immediately by interleaved PCM sample data:
Field Size Meaning
------------ ------ -----------------------------------------
stream_id 4 Accepted playback stream
sequence 4 Monotonically increasing packet sequence
frame_offset 8 First frame's offset from stream start
frame_count 4 Complete sample frames in this Message
media_time 8 Session monotonic time of the first frame
samples variable Interleaved PCM sample data
MWS_AUDIO_PLAYBACK_CLOSE carries only the four-octet stream_id. All
integer fields are unsigned and in network byte order. A stream_id or
sequence value of zero is invalid. A stream_id MUST be unique among
all open or pending Audio streams in the Session. It MUST NOT be
reused until the old stream and its queued data are retired. sequence
starts at 1 and increases by one per DATA Message; the stream MUST be
closed and reopened before sequence exhaustion. frame_offset uses
sample frames as its timebase; the first DATA Message normally has
frame_offset zero. Later Messages MUST begin at or after the end of
the preceding Message's frame range; sample ranges MUST NOT overlap
or move backwards. A gap in frame_offset denotes omitted source
silence. The Portal MUST play that interval as silence, not compress
the stream timeline or repeat preceding samples. Omitting silence
does not create a gap in sequence: each transmitted DATA Message
still increments sequence by one. frame_count MUST be non-zero.
Arithmetic overflow is invalid. DATA payload length MUST equal 28
plus the sample data size. media_time is a non-zero unsigned 64-bit
count of nanoseconds on the Workstation Session media timeline. For a
stream with start time T and sample rate R, the timestamp of frame
offset F is T + floor(F * 1000000000 / R). The Portal MUST validate
that timestamps and frame offsets describe one monotonic stream.
Audio sample formats use established professional Audio-over-IP
representations where one exists:
* L16 -- signed 16-bit linear PCM as specified by [RFC3551]
(sample_format 1)
* L24 -- signed packed 24-bit linear PCM as specified by [RFC3190]
(sample_format 2)
* F32 -- IEEE 754 binary32 PCM [IEEE754] (sample_format 3)
L16 and L24 are the integer PCM interchange formats used by this
protocol. F32 permits an Application which natively produces
floating-point PCM to retain that representation. Implementations
that do not support a given format MUST omit it from their advertised
Audio capabilities.
L16 and L24 samples use signed two's-complement representation and
most-significant-octet-first order as specified by their defining
RFCs. L16 occupies two octets and L24 occupies three packed octets.
F32 occupies four octets in most-significant-octet-first order. Audio
header integers remain in network byte order. A Portal may convert or
pad a sample when passing it to a local audio API, but that local
representation is not sent on the wire. The samples field therefore
contains frame_count multiplied by channel_count and the selected
format's wire width.
Channels are interleaved in frame order. The meaning of channel
positions is mono for one channel and left followed by right for two.
For larger counts, channels are discrete, numbered in interleaving
order from zero; no surround-speaker layout is implied by channel
count.
The Portal MUST either open a playback endpoint with exactly the
proposed parameters and send MWS_AUDIO_PLAYBACK_ACCEPT, or send
MWS_AUDIO_PLAYBACK_REJECT. It MUST NOT silently resample or change
the channel layout. The server MUST NOT send DATA before ACCEPT or
after CLOSE or REJECT. sample_rate, channel_count, and
frames_per_packet MUST be non-zero. The rate, channel count, and
sample format MUST fit the advertised capability envelope. The
preferred packet duration is not a requirement to fill every packet;
senders MUST fit each Message within the peer's receive limits.
MWS_AUDIO_CAPTURE_OPEN (type=620) -- Server -> Portal
Relays an Application request for a Portal capture stream and
its exact parameters.
MWS_AUDIO_CAPTURE_ACCEPT (type=621) -- Portal -> Server
Accepts the proposed capture stream. The Server relays the
answer to the Application across its private client channel.
MWS_AUDIO_CAPTURE_REJECT (type=622) -- Portal -> Server
Rejects the proposed capture stream. The Portal MUST NOT send
capture data for the rejected stream_id. The Server relays the
answer to the Application across its private client channel.
MWS_AUDIO_CAPTURE_DATA (type=623) -- Portal -> Server
Carries timestamped audio for an accepted capture stream.
MWS_AUDIO_CAPTURE_CLOSE (type=624) -- bidirectional
Ends capture at the request of either endpoint. The Server
relays an Application close to the Portal, or a Portal close
to the owning Application, and retires the stream binding.
MWS_AUDIO_CAPTURE_CAPABILITIES (type=625) -- Server -> Library
Repeats the Portal capture envelope from MWS_SESSION_INFO
across the private client channel. This Message does not
traverse the network association. Its payload has the same
layout as MWS_AUDIO_PLAYBACK_CAPABILITIES and describes capture
rather than playback.
Capture OPEN, ACCEPT, REJECT, DATA and CLOSE use the corresponding
playback payload layouts above. Their stream identifiers occupy the
same Session namespace. The Application opens capture; the Portal
accepts or rejects the exact parameters and originates DATA after
acceptance. Either endpoint may close capture. The Portal MUST stop
capture and send CLOSE when permission is revoked, the device is
removed, or it cannot sustain capture within its resource bounds.
Later specifications may define further drift handling and flow
control. No payload may depend on a programming-language type or
host representation.
All Audio Messages in this revision MUST use reliable, ordered
delivery on Stream 4. Control of an Audio stream stays on Stream 4
with its DATA. The corresponding OPEN, ACCEPT, REJECT, DATA, and
CLOSE Messages may also cross the owning Application's client channel
via the Library; they never grant access to another Application's
Audio stream.
A receiver MUST reject DATA for an unknown or unaccepted stream, a
wrong direction, an invalid format, an inconsistent length, or a
non-monotonic frame range. Queues MUST be bounded per stream and per
association. A sender unable to sustain playback within those bounds
MUST close the stream instead of accumulating unbounded data. A
Portal unable to sustain capture MUST close the affected capture
stream. A Portal unable to receive playback MUST report
MWS_ERROR_RESOURCE; if it cannot safely continue, it MUST make the
error fatal and close the association. A recoverable Error alone
does not change stream state.
CLOSE is valid for a pending or accepted stream. A reply already in
flight when CLOSE was sent may be discarded for that closed stream.
In-flight capture DATA sent before either endpoint receives CLOSE may
also be discarded. A well-formed capture CLOSE for an absent stream
MUST be treated as a successful no-op within the attached Session.
This permits crossing CLOSE Messages without retaining closed stream
records, and grants no authority over any other Session. The Portal
MUST release capture access on local close; it MUST NOT wait for an
acknowledgement or a subsequent OPEN. Detach or association loss ends
the negotiated Portal streams; resumed Sessions MUST negotiate fresh
OPEN/ACCEPT exchanges against the new Portal's capabilities before
transmitting Audio DATA.
5.6.1. Session Media Timeline
Playback Audio and Render presentation share one Session media
timeline. Its values are unsigned 64-bit nanosecond counts obtained
from a monotonic Workstation clock. They are neither UTC nor SMPTE
timecodes, and the Portal is not required to synchronise its clock
with the Workstation clock.
A Portal maintains one mapping from the Workstation Session timeline
to its own monotonic clock. The first timestamp received for either
Audio or Render begins a bounded acquisition interval during which
the other plane may arrive. Once established, the same mapping
applies to both planes. The Portal presents each item at the
corresponding Portal time, subject to bounded lateness and the
applicable stale-work policy.
Acquisition MUST be bounded. Audio-only and Render-only Sessions MUST
begin without waiting indefinitely for an absent plane. When both
planes are active, a Portal MAY briefly retain early work so their
relative timing can be preserved. The server validates and routes
timestamps but MUST NOT rewrite them or create a second server-side
presentation clock.
Capture is a separate clock domain. MWS_AUDIO_CAPTURE_DATA carries
non-zero nanoseconds from a monotonic Portal capture clock; its
frame-offset formula is the same as for playback, with T in that
clock domain. The Server preserves those timestamps when delivering
samples to the Library. This revision does not specify
synchronisation of capture with the Workstation timeline; receivers
MUST NOT compare those clocks as if they shared an epoch.
5.7. Protocol State Machine
5.7.1. Initial Connection
portal server streams
====== ====== =======
MWS_QUERY -------------------------------------> Stream 0
MWS_AUTH_CHALLENGE <-------
MWS_AUTH_RESPONSE -----------------------------> Stream 0
MWS_SESSION_INFO <---------(bootstrap
session_id and server receive limits)
MWS_SESSION_INFO ------------------------------> Stream 0
(bootstrap session_id and portal receive limits)
MWS_SESSION_RESUME_OFFER <--
MWS_SESSION_NEW_REQUEST ------------------------> Stream 0
[bootstrap Session continues]
5.7.2. Session Resume
portal server
====== ======
(DTLS/SCTP handshake)
MWS_QUERY ------------------->
<------------------ MWS_AUTH_CHALLENGE
MWS_AUTH_RESPONSE ----------->
<------------------ MWS_SESSION_INFO (bootstrap)
MWS_SESSION_INFO ------------>
<------------------ MWS_SESSION_RESUME_OFFER
MWS_SESSION_RESUME_REQUEST -->
<------------------ MWS_SESSION_INFO
MWS_SESSION_INFO ------------>
<------------------ MWS_SESSION_STATE_BEGIN
<------------------ Window snapshot (Section 5.2.2.1)
<------------------ MWS_SESSION_RESUME_COMPLETE
5.8. WSI Extension (Surface Creation)
MWS describes a provisional Vulkan WSI integration for creating
presentation surfaces associated with Mercurius Windows. The
extension is an integration boundary used beneath the Library's
transparent adaptation of an ordinary Client's native WSI calls. It
does not require the Client to know about Mercurius, enable a
Mercurius extension, include a Mercurius header, or call a Mercurius
entry point.
An MWS surface is created for a window that has previously been
created by the Library after translating the Client's ordinary native
Window operation. The Library exposes an opaque window token to the
WSI implementation. Neither the token nor any SCTP stream,
association, Session, or Window identifier is exposed to the Client.
The declarations below use the C language conventions of the Vulkan
specification. They illustrate a proposed Vulkan API binding, not an
MWS wire format or an allocated Khronos extension. Registration is
addressed in Section 5.8.2.
typedef uint64_t VkMercuriusWindowTokenMWS;
typedef VkFlags VkMercuriusSurfaceCreateFlagsMWS;
typedef struct VkMercuriusSurfaceCreateInfoMWS {
VkStructureType sType;
const void* pNext;
VkMercuriusSurfaceCreateFlagsMWS flags;
VkMercuriusWindowTokenMWS windowToken;
VkExtent2D initialExtent;
} VkMercuriusSurfaceCreateInfoMWS;
VkResult vkCreateMercuriusSurfaceMWS(
VkInstance instance,
const VkMercuriusSurfaceCreateInfoMWS* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface
);
VkMercuriusWindowTokenMWS is opaque. Zero is not a valid token. The
proposed flags field has no defined flags and is zero.
Surface creation proceeds as follows:
1. An unmodified Client creates a native window and requests its
ordinary platform Vulkan surface.
2. The Library translates the native Window operation into an MWS
Window and associates it with an opaque Mercurius window token.
3. Beneath the intercepted native WSI boundary, the Library uses
VK_MWS_surface and calls vkCreateMercuriusSurfaceMWS() with
that token and the requested initial extent.
4. The Library resolves the token to the corresponding MWS Window
and sends the surface creation request to the Server.
5. The Server validates the request against the Client and Session
associated with the local client channel, then creates and
binds the presentation surface for the corresponding Window.
6. The Client continues to perform ordinary Vulkan WSI operations,
including vkGetPhysicalDeviceSurfaceCapabilitiesKHR(),
vkGetPhysicalDeviceSurfaceFormatsKHR(), and
vkCreateSwapchainKHR(). The Library transparently adapts those
operations where required.
Window tokens are valid only within the creating process and MUST NOT
be serialised, persisted, or shared between processes. Their format
is implementation-defined. The Library MUST treat each token as an
uninterpreted value and MUST NOT expose it or derive Mercurius
protocol identifiers, Session identifiers, stream identifiers, or
transport information from it.
The initialExtent field expresses the Client's preferred initial
swapchain dimensions for the window. The server MAY clamp, adjust, or
reject this request according to compositor policy and Vulkan surface
capabilities.
5.8.1. Surface Binding and Session Validation
The windowToken field in VkMercuriusSurfaceCreateInfoMWS is not
authoritative. It is treated only as a request to bind a Vulkan
presentation surface to a Window already known to the Library.
The Library MUST maintain sufficient local state to associate each
exported windowToken with the corresponding Mercurius window,
rendering stream, and Library-managed presentation state. This state
is internal to the Library and is not part of the Client's native WSI
ABI.
When the Server receives a WSI surface creation request, it MUST
validate the request against the Client and Session associated with
the local client channel and against the server-side state associated
with the resolved Window. In particular:
* The token MUST resolve to a Window owned by the Session to which
the requesting Client belongs.
* The resolved window MUST still exist and be eligible for
presentation.
* The Library-managed presentation state associated with the
resolved Window MUST correspond to presentation resources owned
by the requesting Client's Session.
* The server MUST reject any request that attempts to bind a
Vulkan surface to presentation resources not associated with the
authenticated session.
If validation fails, the server MUST reject the request with
MWS_ERROR_SESSION (type=702, fatal=0). The server MUST NOT reveal the
existence, geometry, ownership, visibility, or presentation state of
windows belonging to other sessions.
These rules ensure that Vulkan surface creation cannot be used to
infer or access graphical resources belonging to another user while
still permitting the Library to maintain the internal per-window
state required for ordinary Vulkan applications.
5.8.2. Vulkan Extension Registration
Vulkan extension names, structure types, and other Vulkan registry
values are allocated by the Khronos Group. This document does not
allocate them. The names used in Section 5.8 describe the required
Library-to-Vulkan integration semantics and are provisional until the
corresponding Vulkan extension is registered.
Implementations MUST NOT infer or privately assign a Vulkan numeric
value from this document. Once registered, the extension
specification and Khronos registry are authoritative for the WSI
integration ABI. Such registration does not alter the MWS wire
protocol.
The type VkMercuriusWindowTokenMWS is an opaque unsigned integer type
used solely for Library-initiated surface creation. Its numeric value
has no protocol meaning outside the Library.
5.9. Error Handling (700-799)
Errors are six distinct MWS Message types:
MWS_ERROR (type=700)
An error for which no more specific type applies.
MWS_ERROR_PROTOCOL (type=701)
A malformed Message, unknown opcode, invalid state transition,
wrong stream, or other violation of this specification.
MWS_ERROR_SESSION (type=702)
An invalid Session, Seat, Window, or other Session-scoped
reference.
MWS_ERROR_TRANSPORT (type=703)
A failure while carrying a Message over the Transport.
MWS_ERROR_POLICY (type=704)
A request rejected by authentication, authorisation,
compositor, or other local policy.
MWS_ERROR_RESOURCE (type=705)
A request that cannot be accepted because a required resource
is unavailable or the peer's declared resource limit was
exceeded.
The error type is carried by the MWS header. It is not repeated in
the payload. Every error Message has the following payload:
in_reply_to 2-octet unsigned integer
reserved 2-octet unsigned integer
window_id 4-octet unsigned integer
fatal 4-octet unsigned integer
description_len 4-octet unsigned integer
description description_len octets
All integer fields are in network byte order. in_reply_to is the
opcode of the Message whose processing produced the error, or zero
when no decoded opcode is available. It lets the recipient associate
the error with the failed operation; the error classification remains
the type in the MWS header. reserved MUST be zero. window_id is the
relevant Window identifier, or zero when the error does not concern a
Window or disclosing its identifier would reveal information outside
the peer's Session.
fatal MUST be zero or one. description is an optional UTF-8
diagnostic without a terminating NUL; description_len MAY be zero.
The payload length MUST equal 16 plus description_len.
Error Messages MUST be sent reliably and in order on Stream 0. An
endpoint MUST NOT answer an Error Message with another Error Message;
malformed errors are discarded or cause association termination.
Handshake failures and malformed framing or fragmentation are fatal.
Other rejected operations may use a recoverable error unless their
definitions require termination. Receipt of a recoverable error does
not report the eventual outcome of any other accepted Message. It
reports only that the indicated Message could not be accepted or
completed by the object reporting the error.
A fatal error requires the sender to close the association after
attempting to transmit the error. If the association has already been
lost, or the failed Message header cannot be parsed sufficiently to
address a reply, no error Message can be sent.
Recoverable errors (fatal=0) indicate that the session MAY continue.
Fatal errors (fatal=1) indicate that the SCTP association MUST be
closed immediately after transmitting the error, unless the error
prevents the message from being parsed.
Unexpected loss of the SCTP association (network failure, timeout,
endpoint crash) is treated as a fatal error. The Session MAY persist
according to Section 4.8. Association retirement after receipt of
MWS_SESSION_END is expected terminal completion, not transport loss.
Such a Session cannot be resumed.
All error payload fields follow the network-byte-order rules defined
in Section 5.1.
5.9.1. Session and Resource Validation Errors
Except for Session selection by MWS_SESSION_RESUME_REQUEST, which is
validated against the outstanding offer as specified in Section
5.2.2.1, the Server MUST validate that all window_id, seat_id, and
session_id fields in Portal-originated Messages refer to resources
owned by the authenticated Session associated with the transport
association on which the Message was received. This does not require
any particular internal table or association-ID type.
The following conditions constitute session and resource validation
errors (a subclass of semantic errors) and MUST be reported using
MWS_ERROR_SESSION (type=702, fatal=0):
* referencing a window belonging to another session
* referencing a seat belonging to another session
* attempting to bind a Vulkan surface to a window outside the
authenticated session
* attempting to create or bind a Vulkan surface using
Library-managed presentation state that does not belong to the
authenticated session
* attempting to resume a Session not authorised by the outstanding
offer, or to manipulate resources outside the attached Session
* providing a session_id that does not match the attached Session,
except in an authorised resumption request
When reporting such errors, the server MUST NOT reveal the existence,
geometry, focus state, or any other attributes of resources belonging
to other sessions. The window_id field in the error message MUST be
set to zero if revealing the true identifier would disclose
cross-session state.
These rules ensure that portals cannot infer the presence of other
users, windows, or seats, and that all resource identifiers remain
strictly scoped to the authenticated session.
6. Implementation Guidance
This section is non-normative. It describes one way to organise an
MWS implementation without requiring any programming language,
operating system, toolkit, class hierarchy, or command-line
interface. Conformance is determined solely by the normative
requirements elsewhere in this document.
6.1. Endpoint Independence
A Portal is an independent protocol endpoint. It need not share
source code, data structures, graphics libraries, or an
implementation language with the Server. For example, a Portal
written in Rust or Ruby can interoperate with a Server written in C
by implementing the framing, transport, state machines, payload
encodings, and security requirements defined by this document.
Protocol fields must be decoded from their specified wire
representation. An implementation must not depend on C structure
layout, host byte order, pointer size, alignment, enum
representation, or private Server object types. Capitalised roles
such as Portal, Server, Session, and Window name protocol concepts
rather than required classes.
6.2. Portal Processing Model
A Portal implementation will commonly perform the following
operations:
1. Establish the authenticated Transport association and complete
the Stream 0 handshake in the order specified by Section 5.2.
2. Record the negotiated Session identifier and both peers'
receive limits from the two-way MWS_SESSION_INFO exchange.
3. Maintain independent receive processing for each allocated
stream, while preserving the ordering requirements within each
stream.
4. Maintain a Session-scoped table of Windows using only
identifiers assigned by the Server. Create, configure, map,
unmap, focus, and destroy native presentation resources in
response to the applicable Window Messages.
5. Decode Render Messages on Stream 1 and deliberately supersede
obsolete presentations where permitted. Maintain the highest
contiguous retired Session presentation sequence across both
Render and Video, and send MWS_SESSION_STATUS on Stream 0
without waiting for rendering or native display work.
6. Send input on Stream 2 using the Seat and Window identifiers
belonging to the attached Session. Do not infer authority from
identifiers alone.
7. On detach, association loss, or resume, discard or reconstruct
local presentation state exactly as required by the Session
state machine.
A Portal may use threads, asynchronous tasks, an event loop, or
another concurrency model. The observable Message ordering and
prioritisation are the interoperability requirements.
6.3. Concurrency and Backpressure
Control processing must remain available while rendering is slow or
blocked. In particular, a Portal must be able to originate
MWS_SESSION_STATUS, process errors, and respond to Session and Window
lifecycle Messages without waiting for a native renderer to finish a
presentation.
Render flight limits constrain cumulative outstanding work; payload
and user-message limits constrain individual Messages. None is a
suggested allocation size. A Portal must advertise limits it can
actually sustain and must account for fragmented Messages until they
are completed or abandoned. Independent associations and Sessions
must have independent state; a slow Session must not consume another
Session's identifiers, progress frontier, or flow-control credit.
Implementations should validate lengths and identifiers before
allocation or dispatch. Bounded queues, checked arithmetic, explicit
ownership, and timely disposal of superseded Render data are
particularly important when Messages originate from an untrusted
endpoint.
6.4. Version Scope
An implementation may omit an optional facility, but it must not emit
a Message whose payload this version leaves undefined. Reserved
opcodes and streams remain reserved. Unknown or misplaced Messages
are handled according to Section 5.9; an implementation must not
guess their layout from an opcode range or from another
implementation's private behaviour.
This experimental revision changes wire formats from earlier drafts.
Deployments must configure both endpoints for this protocol revision.
The Session Info version fields report each endpoint's implementation
version; neither those values nor the ALPN identifier negotiate or
establish draft-version compatibility.
Implementers may use published source code and test programs as
additional interoperability evidence, but such material does not
extend or override this specification.
6.5. Reference Implementation Components
The Mercurius reference implementation provides the following
components. Their names and internal division are non-normative; an
interoperable implementation may organise the same protocol roles
differently.
mwsd The Server daemon. It owns authoritative Session, Window,
rendering, application-execution, and policy state and accepts Portal
associations and local client channels.
mwsc The Portal program. It authenticates to a Server, presents
Session Windows through the native display system, and returns user
interaction and Portal status to the Server.
libmws/compat and libmws These divide the Library role defined in
this document. libmws/compat supplies compatibility interposition for
unmodified Clients; libmws supplies the underlying Mercurius protocol
facilities. An ordinary Client such as radialblur neither calls
Mercurius interfaces nor links directly against libmws.
mwsdm The Session selector used when no Client command is specified.
It runs in the authenticated bootstrap Session and allows the user to
continue that Session as new or replace it with an eligible existing
Session.
mlogo A minimal demonstration Client deliberately linked against
libmws. Inspired by xlogo, it is the "is this thing on?" proof of a
Mercurius installation. Launching, displaying, resizing, and closing
mlogo exercises the core Client launch, local client-channel, Window
lifecycle, rendering, and Portal-association path without
compatibility interposition.
6.6. Usage Examples
This section is non-normative. It uses commands from the reference
implementation to illustrate the MWS usage model. Other
implementations may provide different user interfaces while producing
the same protocol behaviour. These examples include the intended
detach/resume workflow; they do not assert that every described
facility is implemented in the current reference software. In
particular, transport encryption and explicit detach/resume remain
implementation work.
Assume xavier.example is a workstation running an MWS Server, while
flash and torch are devices acting as Portals.
6.6.1. SSH and MWS
SSH and MWS provide complementary ways to use the same workstation:
flash$ ssh alice@xavier.example uptime
flash$ mwsc alice@xavier.example mlogo
The first command runs a command-line program through SSH. The second
asks the MWS Server to run a graphical Client in Alice's Session and
present its Window on flash. MWS does not carry this connection over
SSH; the similarity is the user-facing model of authenticating to a
workstation and requesting a program there.
6.6.2. Session Selection
Omitting a Client command requests the graphical Session selector:
flash$ mwsc alice@xavier.example
The Portal authenticates Alice before the bootstrap Session is
established. The Server then runs mwsdm in that Session. Because the
remote user is already authenticated, mwsdm does not request the
credentials again. It offers Alice the choice of continuing the
bootstrap Session as a new Session or replacing it with one of
Alice's eligible existing Sessions.
In a local-console deployment, the local Portal and Server perform
the same protocol roles and still require authentication before
establishing the bootstrap Session. A local login interface may
collect credentials before that exchange; this does not grant an
unauthenticated Session.
6.6.3. Detach and Resume
Alice may explicitly detach a Session on flash and request either
that its Clients continue executing or that they remain suspended,
subject to Server policy. Later, from torch, Alice connects to the
same workstation:
torch$ mwsc alice@xavier.example
After authentication, the Session selector offers the detached
Session. If Alice resumes it, its server-resident Clients remain the
same Clients and its Windows are reconstructed on torch; they are not
restarted merely because a different Portal now provides the Seat.
An unexpected network interruption is different from explicit detach.
It places the Session in the bounded GRACE state described in
Section 4.8 rather than granting indefinite lifetime.
6.6.4. Local and Remote Portals
A Portal may be on the workstation itself or on another device. The
reference Portal selects the local Transport when the named host is
the workstation on which it is running, including when that host is
named by its short hostname or by a fully qualified name which
resolves to a local address. Local selection therefore does not
require localhost or an explicit local option. For example, each of
the following selects the local Transport:
xavier$ mwsc -l mlogo
xavier$ mwsc --local mlogo
xavier$ mwsc localhost mlogo
flash$ mwsc alice@flash mlogo
flash$ mwsc alice@flash.example mlogo
A remote Portal selects the network Transport:
flash$ mwsc alice@xavier.example mlogo
The protocol's Session, Window, and Seat semantics are identical in
both cases. Local operation is not a separate window-system mode and
does not imply a single console, Portal, Seat, or user. A workstation
may serve multiple local users concurrently through independent local
Portal associations, for example using displays and input devices
attached through one or more USB-C docks. Each local association
remains bound to its own authenticated Session and receives the same
identifier, authority, and isolation treatment as a network
association.
6.6.5. Independent Portals
Several users or Sessions may use one Server concurrently:
flash$ mwsc alice@xavier.example mlogo
torch$ mwsc bob@xavier.example mlogo
Each association has its own authenticated Session context,
identifiers, flow-control state, and rendering progress. Slowness or
failure at one Portal must not block control processing or reserve
another Portal's capacity.
7. Implementation Requirements and Validation
This section defines normative requirements for any conformant MWS
implementation. These requirements ensure correct behaviour under
load, predictable session semantics, and robust isolation between
portals.
7.1. Test Matrix
An implementation of MWS MUST demonstrate correct behaviour across
four major dimensions:
* Session semantics -- creation, resume, detachment, identifier
stability, and state continuity.
* Window lifecycle -- creation, mapping, resizing, destruction,
and identifier scoping.
* Rendering correctness -- surface creation, command ordering, GPU
isolation, and frame delivery.
* Transport behaviour -- SCTP stream allocation, ordering
guarantees, error handling, and reconnection.
The following matrix defines the minimum set of tests required to
validate interoperability between an MWS portal and server. These
tests are not exhaustive; they represent the baseline necessary to
confirm that the architectural components described in this document
behave as specified.
7.1.1. Core Validation Tests
Bootstrap and rendering:
Establish a Session between independently implemented endpoints
and render a minimal surface. An initial frame MUST be displayed
by the Portal, and the Session MUST terminate or detach cleanly.
Window lifecycle:
Create, map, unmap, and destroy a Window while observing
compositor events. The CREATE, MAP, UNMAP, and DESTROY sequence
MUST be correct, and no resources may be orphaned.
Session persistence:
Start a Session, detach it or allow the Portal to disconnect, and
then resume it using the same Session identifier. The compositor
state MUST be reconstructed as defined in Sections 4.8, 4.9, and
5.2.2, and the Portal MUST be able to redraw without a protocol
violation.
GPU isolation:
Run multiple Portals concurrently, each creating independent
surfaces. There MUST be no cross-Session resource leakage;
surfaces and Windows MUST remain isolated.
Transport stream allocation:
Exercise the defined control, rendering, input, and audio traffic.
Exercise accepted HEVC Video presentation and its retirement
handshake. Verify that Messages reserved for later specification
are not emitted. Messages MUST NOT be reordered where their class
requires ordered delivery, and routing by Session, Seat, logical
stream, and Window identifier MUST remain correct.
Transport fragmentation:
Negotiate max_user_message_size below the size of a
MWS_RENDER_PRESENT. Transport MUST emit a valid MWS_MESSAGE_START
and MWS_MESSAGE_APPEND sequence, and the peer MUST deliver exactly
one reconstructed MWS_RENDER_PRESENT with an identical header and
payload. Simultaneous associations with different limits MUST
reassemble independently. Losing an association with a fragmented
Message in progress MUST NOT deliver an incomplete Message or
consume a later Message as continuation data. A fragmented
MWS_RENDER_PRESENT MUST be completed rather than abandoned.
Separately, using a Message whose abandonment is permitted by this
revision, verify that MWS_MESSAGE_ABANDON discards the incomplete
Message and permits the next Message on that stream to be
processed normally.
Error handling:
Send invalid identifiers, malformed Messages, and protocol
violations. The server MUST return the applicable error Message
from the 700-799 range while preserving Session integrity unless
the error is fatal.
7.2. GPU Isolation Requirements
Implementations MUST ensure that GPU workloads from one session
cannot compromise the integrity or confidentiality of another
session's resources, regardless of whether the server contains a
single GPU or multiple GPUs.
* The server SHOULD avoid allowing GPU workloads from one session
to starve or block those of another. Implementations MAY use
separate Vulkan queues, queue subsets, per-session scheduling
domains, or multi-GPU distribution strategies to achieve this.
* The workstation MUST isolate Client GPU execution through its
graphics stack and operating-system protection boundaries. An
implementation accepting untrusted command submissions MUST
validate or contain them sufficiently to prevent out-of-bounds
access to another Session's resources. The MWS wire protocol
does not require a Portal to submit Vulkan command buffers.
* The server MUST enforce per-session limits on GPU resource
usage, including device memory, descriptor sets, and command
buffer size. When limits are exceeded, the server MAY throttle,
reject further submissions, or terminate the session. On systems
with multiple GPUs, implementations MAY assign sessions to
different GPUs to improve isolation or load distribution.
* The server SHOULD implement watchdog mechanisms to detect and
recover from GPU hangs attributable to a particular session.
Recovery MAY include resetting portal queues, revoking
swapchains, or terminating the offending session while
preserving other sessions. On multi-GPU systems, recovery MAY
include migrating unaffected sessions to other GPUs.
7.3. Bandwidth and Transport Isolation Requirements
Implementations MUST ensure that control and input remain responsive
under load and that one portal cannot monopolise transport resources
to the detriment of others.
* Servers using a one-to-many SCTP socket MUST NOT treat writable
readiness of that socket as readiness of a particular
association. The SCTP sockets API explicitly permits writable
readiness to mean that only one of the represented associations
is writable [RFC6458]. To keep the handshake cheap,
implementations SHOULD defer association-specific resources
until authentication has succeeded. They SHOULD then isolate the
association with sctp_peeloff(), or use an equivalent
association-specific readiness and queueing mechanism, before
sending MWS_SESSION_INFO.
* Outbound buffering and backpressure MUST be tracked per
association. A stalled association MUST NOT delay sends to
another association. Implementations MUST bound per-association
queued data so that one portal cannot exhaust workstation
memory.
* Stream 0 (control) MUST use reliable, ordered delivery and MUST
be prioritised over every non-control stream. All stream
priorities follow Section 4.7. Input delivery follows Section
5.4.
* Stream 1 (rendering Messages) MUST use reliable, ordered
delivery. The server MAY impose rate limits on
MWS_RENDER_PRESENT and client-channel rendering Messages to
prevent excessive queueing.
* Stream 2 carries input according to the per-event reliability,
ordering, and coalescing requirements in Section 5.4.
* Stream 3 carries MWS_VIDEO_DATA and MWS_VIDEO_CLOSE reliably
and in order. FORMATS, OPEN and STATUS use Control.
* Stream 4 carries audio. Each audio Message definition MUST state
its ordering, loss, buffering, and flow-control requirements.
* Stream 5 carries bulk reliably and in order, at lower priority
than every other assigned stream, including rendering. Bulk
traffic MUST remain bounded by its Message-specific flow
control.
* The server SHOULD implement per-session or per-portal bandwidth
limits to prevent link saturation. Limits MAY be enforced at the
SCTP layer, via traffic shaping, or using equivalent mechanisms.
* The server MUST be able to unilaterally terminate a misbehaving
portal without impacting other sessions. Termination SHOULD be
signalled with the applicable fatal error Message followed by
closure of the SCTP association, as defined in Section 5.9.
Termination MUST release all GPU, transport, and compositor
resources owned solely by that Portal attachment.
Server-resident Session resources follow the GRACE and DETACHED
lifecycles in Section 4.8; other active Sessions MUST NOT be
affected.
8. Performance Considerations
MWS was designed only after exploratory measurements indicated that
the intended network-native architecture was technically plausible.
These measurements were a feasibility study, not a benchmark of a
complete Mercurius implementation.
In the reference environment, the prospective Portal and workstation
were located in different buildings. The path crossed a 10 GbE link,
two switches, and a 10 Gbit/s fibre link. A 20-second, single-flow
TCP test using fio's network engine and an I/O depth of one reported
sustained throughput of approximately 1.3-1.5 Gbit/s. Representative
ICMP measurements within the same site reported round-trip times of
0.181-0.339 ms, with a mean of 0.293 ms.
These observations established that neither available bandwidth nor
site-network propagation delay was an immediate obstacle to exploring
a network-native Window system. They do not measure SCTP or DTLS
overhead, GPU encoding, Portal decoding, display scheduling, or the
complete input-to-display path. The completion latency reported by a
local socket write is likewise not a measurement of network transit
time.
The reference workstation contains an NVIDIA GeForce RTX 5070. NVIDIA
documents that device as providing a ninth-generation NVENC encoder
with AV1 support [RTX50]. NVENC is dedicated encoding hardware and
can operate independently of the graphics and CPU cores [NVENC].
These published capabilities supported the feasibility decision, but
they are not measurements of Mercurius encode latency, processor use,
or achievable resolution and refresh rate.
No end-to-end performance figures are claimed by this specification.
Implementations should measure at least transport latency and
throughput, encode and decode latency, display scheduling delay,
input-to-display latency, processor and GPU utilisation, and tail
latency under concurrent Session load. Results should identify the
measured boundary, topology, Message sizes, transport security,
sample count, and percentile distribution.
The protocol nevertheless provides mechanisms intended to avoid
unnecessary interference between traffic classes. Control, rendering,
input, video, audio and bulk use separate SCTP streams, and buffering
is bounded per association. These properties reduce avoidable
head-of-line blocking but do not guarantee any particular latency,
throughput, or user experience.
9. Security Considerations
MWS is designed according to zero-trust principles: no portal device,
network segment, or intermediary is implicitly trusted. All trust is
derived from cryptographic identity and explicit authorisation rather
than network location. The protocol assumes that portal devices may
be compromised, mobile, or operating on hostile networks, and that
attackers may observe, inject, or replay traffic unless prevented by
cryptographic protections.
Transport security is provided by DTLS 1.3 over SCTP using
[I-D.6083BIS]. The Portal authenticates the server certificate, and
DTLS provides confidentiality and integrity for MWS traffic. When
DANE is deployed, the server certificate is validated against
DNSSEC-protected TLSA records. Deployments without DNSSEC or without
control over their DNS zone SHOULD use traditional PKI validation
instead.
User authentication is performed at the application layer using the
mechanism-agnostic model defined in Section 5.2.1. The server
advertises supported mechanisms (for example, "PAM", "FIDO2") as
UTF-8 identifiers in MWS_AUTH_CHALLENGE, and the portal selects one.
This separation of device and user identity ensures that device
identity alone does not grant access to a user's Session.
Cryptographic proofs of possession of reusable credentials MUST be
bound to the current DTLS association. In particular, SSHKEY signs
the tls-exporter channel binding defined by [RFC9266]. A response
captured on one association therefore cannot authenticate a new
association. PAM is a password transfer rather than such a proof and
has the limitations stated in Appendix B.1. Authentication data
received from a Portal MUST NOT be treated as evidence of freshness
unless the server can derive and verify that freshness independently.
Each user is given an isolated session and compositor context.
Portals cannot observe or interfere with other users' windows, input
events, or rendering state. Window identifiers are scoped to a
session, and all portal-originated messages are validated by the
server. Attempts to reference resources outside the authenticated
session are rejected with MWS_ERROR_SESSION (type=702) as described
in Section 5.9.
Portal-association rendering Messages use a dedicated SCTP stream.
Input and Audio use Streams 2 and 4 with the validation and ordering
rules in Sections 5.4 and 5.6. A Server MUST restrict input to the
attached Session and capture to accepted streams. Capture requires
Portal-local permission and remains subject to server policy.
Implementations MUST bound decompression, reassembly, Render, and
Audio and Video buffers before consuming untrusted data. Video
decoding MUST enforce the accepted dimensions, profile and payload
bounds before native presentation, without relaxing Session ownership
checks.
The server does not trust a Portal as an authority over Session state
or resources. An active Portal is nevertheless trusted by its user
with displayed content, captured input, and any reusable credential
stored or entered there. Compromise of that Portal can compromise
that user, but MUST NOT cross Session or user boundaries. If a portal
disconnects unexpectedly, the session persists only for the duration
of the reconnection grace period unless the user has explicitly
detached. After this period, the session is terminated and all
associated resources are destroyed, as defined in Section 4.8.
Unexpected loss of the transport association (network failure,
timeout, endpoint crash) is treated as a fatal transport error. The
Session MAY persist according to Section 4.8 and MAY be resumed from
another Portal subject to policy. MWS_SESSION_END instead announces
committed termination: subsequent association retirement is expected,
and that Session MUST NOT be resumed.
Explicit detachment is requested with MWS_SESSION_DETACH (type=103).
It is distinct from unexpected association loss: detachment records
the user's intention to detach and preserve the Session, whereas
association loss enters the bounded reconnection grace period.
9.1. DANE Deployment (Non-Normative)
Deployments that operate their own DNS infrastructure may use DNSSEC
and TLSA records (DANE) to authenticate server certificates during
the DTLS/SCTP handshake. When DNSSEC validation is available, DANE
provides a robust mechanism for binding workstation identity to DNS
without relying on public certificate authorities.
In this model, the portal validates the server's certificate against
DNSSEC-protected TLSA records before proceeding with the MWS
handshake, ensuring that it is communicating with the intended
workstation even in the presence of compromised or mis-issued CA
certificates.
DANE is optional. Its identity and failure rules are specified in
Section 4.11 and apply before MWS user authentication. When enabled,
it reduces operational complexity in closed trust domains by
eliminating external trust dependencies and mitigating
man-in-the-middle attacks even in the event of public CA compromise.
Deployments without DNSSEC or without administrative control over
their DNS zone should use traditional PKI validation instead.
10. IANA Considerations
This document requests three IANA actions:
1. Register the following entry in the Service Name and Transport
Protocol Port Number Registry:
Service Name: mws
Port Number: TBD1
Transport Protocol: SCTP
Description: Mercurius Window System
Assignee: IESG <iesg@ietf.org>
Contact: IETF Chair <chair@ietf.org>
Reference: This document
IANA is requested to allocate TBD1 from the Registered Port
range. The RFC Editor is requested to replace every occurrence
of TBD1 with the assigned port number before publication.
2. Register the following entry in the TLS Application-Layer
Protocol Negotiation (ALPN) Protocol IDs registry [RFC7301]:
Protocol: Mercurius Window System
Identification Sequence: 0x6d 0x77 0x73 ("mws")
Reference: This document
3. Register an entry in the SCTP Payload Protocol Identifiers
registry, following Section 4.3 of [I-D.6083BIS]:
Value: TBD2
SCTP Payload Protocol Identifier:
Mercurius Window System over DTLS
Reference: This document
The cited mapping does not assign a generic DTLS PPID. TBD2
identifies SCTP user messages carrying DTLS records for MWS; ALPN
identifies the application protocol during DTLS establishment. The
RFC Editor is requested to replace TBD2 with the assigned PPID before
publication. TBD1 and TBD2 are allocation placeholders, not wire
values. Experiments before allocation require explicitly agreed local
values and MUST NOT represent those values as IANA assignments.
No other registries are required. In particular, MWS message types,
opcodes, and SCTP stream assignments are managed entirely within the
protocol and do not require IANA allocation.
11. Acknowledgements
Christopher Ross (chris@tebibyte.org) provided the initial design and
the reference implementation.
The reference implementation described in Section 6 is maintained in
the Mercurius source code repository. Git and SSH access are
available to contributors on request via mercurius@tebibyte.org.
Additional background material, including architectural
rationale, design philosophy, and example use cases, is available
from the Mercurius project website
<https://mercurius.tebibyte.org>. This information is provided
for context only and is non-normative; the protocol defined in
this document is complete and does not depend on any specific
implementation or external documentation.
12. References
12.1. Normative References
[AVC] ITU-T, "Advanced video coding for generic audiovisual
services", Recommendation H.264,
<https://www.itu.int/rec/T-REC-H.264>.
[HEVC] ITU-T, "High efficiency video coding", Recommendation H.265,
January 2026, <https://www.itu.int/rec/T-REC-H.265-202601-I>.
[DBUS] freedesktop.org, "D-Bus Specification", Version 0.43,
29 October 2024,
<https://dbus.freedesktop.org/doc/dbus-specification.html>.
[HUT17] USB Implementers Forum, "HID Usage Tables", Version 1.7, 27
January 2026,
<https://usb.org/document-library/hid-usage-tables-17>.
[I-D.6083BIS] Tuexen, M., Tschofenig, H., and T. Reddy, "Datagram
Transport Layer Security (DTLS) 1.3 for Stream Control
Transmission Protocol (SCTP)", Work in Progress,
Internet-Draft, draft-tuexen-tsvwg-rfc6083-bis-07, 21 April
2025,
<https://www.ietf.org/archive/id/
draft-tuexen-tsvwg-rfc6083-bis-07.txt>.
[IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", IEEE
Std 754-2019, July 2019,
<https://standards.ieee.org/ieee/754/6210/>.
[POSIX-EXEC] The Open Group, "exec", The Open Group Base
Specifications, Issue 8, POSIX.1-2024,
<https://pubs.opengroup.org/onlinepubs/9799919799/
functions/exec.html>.
[RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982,
DOI 10.17487/RFC1982, August 1996,
<https://www.rfc-editor.org/info/rfc1982>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI
10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3190] Kobayashi, K., Ogawa, A., Casner, S., and C. Bormann, "RTP
Payload Format for 12-bit DAT Audio and 20- and 24-bit
Linear Sampled Audio", RFC 3190, DOI 10.17487/RFC3190,
January 2002,
<https://www.rfc-editor.org/info/rfc3190>.
[RFC3551] Schulzrinne, H. and S. Casner, "RTP Profile for Audio and
Video Conferences with Minimal Control", STD 65, RFC 3551,
DOI 10.17487/RFC3551, July 2003,
<https://www.rfc-editor.org/info/rfc3551>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003,
<https://www.rfc-editor.org/info/rfc3629>.
[RFC4251] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
Protocol Architecture", RFC 4251, DOI 10.17487/RFC4251,
January 2006,
<https://www.rfc-editor.org/info/rfc4251>.
[RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253,
January 2006,
<https://www.rfc-editor.org/info/rfc4253>.
[RFC4895] Tuexen, M., Stewart, R., and P. Lei, "Authenticated Chunks
for Stream Control Transmission Protocol (SCTP)", RFC 4895,
DOI 10.17487/RFC4895, August 2007,
<https://www.rfc-editor.org/info/rfc4895>.
[RFC6458] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V.
Yasevich, "Sockets API Extensions for the Stream Control
Transmission Protocol (SCTP)", RFC 6458, DOI
10.17487/RFC6458, December 2011,
<https://www.rfc-editor.org/info/rfc6458>.
[RFC6698] Hoffman, P. and J. Schlyter, "The DNS-Based Authentication
of Named Entities (DANE) Transport Layer Security (TLS)
Protocol: TLSA", RFC 6698, DOI 10.17487/RFC6698, August
2012,
<https://www.rfc-editor.org/info/rfc6698>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/info/rfc6838>.
[RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan,
"Transport Layer Security (TLS) Application-Layer Protocol
Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
July 2014,
<https://www.rfc-editor.org/info/rfc7301>.
[RFC7671] Dukhovni, V. and W. Hardaker, "The DNS-Based Authentication
of Named Entities (DANE) Protocol: Updates and Operational
Guidance", RFC 7671, DOI 10.17487/RFC7671, October 2015,
<https://www.rfc-editor.org/info/rfc7671>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119
Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May
2017,
<https://www.rfc-editor.org/info/rfc8174>.
[RFC8332] Bider, D., "Use of RSA Keys with SHA-256 and SHA-512 in the
Secure Shell (SSH) Protocol", RFC 8332, DOI
10.17487/RFC8332, March 2018,
<https://www.rfc-editor.org/info/rfc8332>.
[RFC8709] Harris, B. and L. Velvindron, "Ed25519 and Ed448 Public Key
Algorithms for the Secure Shell (SSH) Protocol", RFC 8709,
DOI 10.17487/RFC8709, February 2020,
<https://www.rfc-editor.org/info/rfc8709>.
[RFC8878] Collet, Y. and M. Kucherawy, Ed., "Zstandard Compression
and the 'application/zstd' Media Type", RFC 8878, DOI
10.17487/RFC8878, February 2021,
<https://www.rfc-editor.org/info/rfc8878>.
[RFC9147] Rescorla, E., Tschofenig, H., and N. Modadugu, "The
Datagram Transport Layer Security (DTLS) Protocol Version
1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022,
<https://www.rfc-editor.org/info/rfc9147>.
[RFC9260] Stewart, R., Tuexen, M., and K. Nielsen, "Stream Control
Transmission Protocol", RFC 9260, DOI 10.17487/RFC9260,
June 2022,
<https://www.rfc-editor.org/info/rfc9260>.
[RFC9266] Whited, S., "Channel Bindings for TLS 1.3", RFC 9266, DOI
10.17487/RFC9266, July 2022,
<https://www.rfc-editor.org/info/rfc9266>.
[RFC9525] Saint-Andre, P. and R. Salz, "Service Identity in TLS",
RFC 9525, DOI 10.17487/RFC9525, November 2023,
<https://www.rfc-editor.org/info/rfc9525>.
[VK14] Khronos Group, "Vulkan 1.4 Specification", version 1.4.362,
September 2026,
<https://registry.khronos.org/vulkan/specs/latest/html/
vkspec.html>.
12.2. Informative References
[EWMH] freedesktop.org, "Extended Window Manager Hints", Section 5,
"Application Window Properties",
<https://specifications.freedesktop.org/wm/latest/
ar01s05.html>.
[NIST800-207] National Institute of Standards and Technology, "Zero
Trust Architecture", NIST Special Publication 800-207, DOI
10.6028/NIST.SP.800-207, August 2020,
<https://csrc.nist.gov/pubs/sp/800/207/final>.
[NVENC] NVIDIA Corporation, "NVENC Application Note", NVIDIA Video
Codec SDK 13.0, 2025,
<https://docs.nvidia.com/video-technologies/
video-codec-sdk/13.0/nvenc-application-note/>.
[RFC3436] Jungmaier, A., Rescorla, E., and M. Tuexen, "Transport
Layer Security over Stream Control Transmission Protocol",
RFC 3436, DOI 10.17487/RFC3436, December 2002,
<https://www.rfc-editor.org/info/rfc3436>.
[RFC6083] Tuexen, M., Seggelmann, R., and E. Rescorla, "Datagram
Transport Layer Security (DTLS) for Stream Control
Transmission Protocol (SCTP)", RFC 6083, DOI
10.17487/RFC6083, January 2011,
<https://www.rfc-editor.org/info/rfc6083>.
[RFC8261] Tuexen, M., Stewart, R., Jesup, R., and S. Loreto,
"Datagram Transport Layer Security (DTLS) Encapsulation
of SCTP Packets", RFC 8261, DOI 10.17487/RFC8261,
November 2017,
<https://www.rfc-editor.org/info/rfc8261>.
[RFC8831] Jesup, R., Loreto, S., and M. Tuexen, "WebRTC Data
Channels", RFC 8831, DOI 10.17487/RFC8831, January 2021,
<https://www.rfc-editor.org/info/rfc8831>.
[RTX50] NVIDIA Corporation, "GeForce RTX 50 Series GPUs Double
Creative Performance", January 2025,
<https://blogs.nvidia.com/blog/
generative-ai-studio-ces-geforce-rtx-50-series/>.
[SARATOGA] Wood, L., Eddy, W., Smith, C., Ivancic, W., and C.
Jackson, "Saratoga: A Scalable Data Transfer Protocol",
Work in Progress, Internet-Draft,
draft-wood-tsvwg-saratoga-22, 17 December 2017,
<https://datatracker.ietf.org/doc/
draft-wood-tsvwg-saratoga/22/>.
[WAYLAND] Wayland project, "Wayland Architecture",
<https://wayland.freedesktop.org/architecture.html>.
[XDG-ICON] Wayland project, "xdg-toplevel-icon-v1", version 1,
wayland-protocols staging protocol,
<https://gitlab.freedesktop.org/wayland/wayland-protocols/
-/blob/main/staging/xdg-toplevel-icon/
xdg-toplevel-icon-v1.xml>.
[XDG-SETTINGS] XDG Desktop Portal authors, "Settings",
<https://flatpak.github.io/xdg-desktop-portal/docs/
doc-org.freedesktop.portal.Settings.html>.
Appendix A. MWS Opcode Registry
This appendix defines the MWS opcode allocations for this revision.
All opcodes are 16-bit unsigned integers. Opcodes are grouped into
100-entry ranges according to functional category. Implementations
MUST treat unknown opcodes as protocol errors and respond with
MWS_ERROR_PROTOCOL (type=701) as described in Section 5.9.
Within each standard category, offsets 00-49 are available for
Messages in the current protocol family. Values not allocated below
are unassigned and remain available for future specifications.
Offsets 50-99 are reserved to leave substantial space for later major
revisions of Mercurius. The experimental range is the exception to
this convention. Opcodes 1000-65535 are unassigned and MUST NOT be
emitted by implementations of this revision.
A.1. Handshake and Authentication (000-099)
NOTE: Type 000 is reserved and MUST be treated as a NULL/invalid
value. Implementations encountering type=000 MUST respond with
MWS_ERROR_PROTOCOL (type=701, fatal=1).
001 MWS_QUERY
002 MWS_AUTH_CHALLENGE
003 MWS_AUTH_RESPONSE
004 MWS_SESSION_INFO
005-049 Unassigned
050-099 Reserved for later protocol revisions
A.2. Session Management (100-199)
100 MWS_SESSION_RESUME_OFFER
101 MWS_SESSION_RESUME_REQUEST
102 MWS_SESSION_RESUME_COMPLETE
103 MWS_SESSION_DETACH
104 MWS_SESSION_NEW_REQUEST
105 MWS_SESSION_STATE_BEGIN
106 MWS_SESSION_STATUS
107 MWS_SESSION_CLOSE_REQUEST
108 MWS_SESSION_END
109 Unassigned
110 MWS_EXEC_REQUEST
111 MWS_EXEC_RESULT
112 MWS_EXEC_STDOUT
113 MWS_EXEC_STDERR
114-119 Unassigned
120 MWS_CONFIG_QUERY
121 MWS_CONFIG_RESULT
122 MWS_CONFIG_WATCH
123 MWS_CONFIG_UNWATCH
124 MWS_CONFIG_UPDATE
125-129 Unassigned
130 MWS_CLIPBOARD_PUBLISH
131 MWS_CLIPBOARD_REQUEST
132 MWS_CLIPBOARD_RESULT
133 MWS_CLIPBOARD_CANCEL
134-139 Unassigned
140 MWS_DBUS_CAPABILITIES
141 MWS_DBUS_PEER
142 MWS_DBUS_MESSAGE
143 MWS_DBUS_CREDIT
144 MWS_DBUS_CLOSE
145-149 Unassigned
150-199 Reserved for later protocol revisions
A.3. Window Lifecycle (200-299)
200 MWS_CREATE_WINDOW
201 MWS_WINDOW_CREATED
202 MWS_DESTROY_WINDOW
203 MWS_WINDOW_DESTROYED
204 MWS_MAP_WINDOW
205 MWS_UNMAP_WINDOW
206 MWS_CONFIGURE_WINDOW
207 MWS_FOCUS_WINDOW
208 MWS_SWAPCHAIN_REVOKED
209 MWS_WINDOW_STATE
210 MWS_WINDOW_RELATION
211 MWS_WINDOW_TITLE
212 MWS_WINDOW_ICON
213 MWS_WINDOW_CURSOR
214 MWS_WINDOW_IDENTITY
215 MWS_WINDOW_ACTION
216 MWS_WINDOW_CLOSE_REQUEST
217 MWS_WINDOW_SIZE_REQUEST
218 MWS_WINDOW_STATUS
219 MWS_WINDOW_FRAME_EXTENTS
220 MWS_WINDOW_INTERACTION_BEGIN
221 MWS_WINDOW_INTERACTION_STATUS
222 MWS_WINDOW_INTERACTION_END
223 MWS_WINDOW_INTERACTION_INPUT
224 MWS_TASK_MODEL_READY
225 MWS_TASK_DESCRIPTION
226 MWS_TASK_ACTION
227 MWS_DECORATOR_READY
228 MWS_DECORATION_REQUEST
229 MWS_DECORATION_FRAME
230 MWS_DECORATION_INPUT
231 MWS_DECORATION_STATE
232 MWS_DESKTOP_OFFER
233 MWS_DESKTOP_ACCEPT
234 MWS_DESKTOP_REVOKE
235 MWS_DESKTOP_STATE
236-249 Unassigned
250-299 Reserved for later protocol revisions
A.4. Rendering Messages (300-399)
300 MWS_RENDER_PRESENT
301 MWS_RENDER_SYNC
302 MWS_RENDER_DESTROY
303 MWS_RENDER_UPLOAD
304 MWS_RENDER_DAMAGE
305 MWS_RENDER_FENCE
306-349 Unassigned
350-399 Reserved for later protocol revisions
A.5. Input Plane (400-499)
400 MWS_INPUT_EVENT
401 MWS_INPUT_ACK
402 MWS_INPUT_POINTER_MODE
403-449 Unassigned
450-499 Reserved for later protocol revisions
A.6. Video Plane (500-599)
500 MWS_VIDEO_FORMATS
501 MWS_VIDEO_OPEN
502 MWS_VIDEO_STATUS
503 MWS_VIDEO_DATA
504 MWS_VIDEO_CLOSE
505-549 Unassigned
550-599 Reserved for later protocol revisions
A.7. Audio Plane (600-699)
600 MWS_AUDIO_PLAYBACK_OPEN
601 MWS_AUDIO_PLAYBACK_ACCEPT
602 MWS_AUDIO_PLAYBACK_REJECT
603 MWS_AUDIO_PLAYBACK_DATA
604 MWS_AUDIO_PLAYBACK_CLOSE
605 MWS_AUDIO_PLAYBACK_CAPABILITIES
606-619 Unassigned
620 MWS_AUDIO_CAPTURE_OPEN
621 MWS_AUDIO_CAPTURE_ACCEPT
622 MWS_AUDIO_CAPTURE_REJECT
623 MWS_AUDIO_CAPTURE_DATA
624 MWS_AUDIO_CAPTURE_CLOSE
625 MWS_AUDIO_CAPTURE_CAPABILITIES
626-649 Unassigned
650-699 Reserved for later protocol revisions
A.8. Error Reporting (700-799)
700 MWS_ERROR
701 MWS_ERROR_PROTOCOL
702 MWS_ERROR_SESSION
703 MWS_ERROR_TRANSPORT
704 MWS_ERROR_POLICY
705 MWS_ERROR_RESOURCE
706-749 Unassigned
750-799 Reserved for later protocol revisions
A.9. Transport Services (800-899)
800 MWS_MESSAGE_START
801 MWS_MESSAGE_APPEND
802 MWS_MESSAGE_ABANDON
803-849 Unassigned for Transport-to-Transport Messages
850-899 Reserved for later protocol revisions
A.10. Experimental and Vendor-Specific (900-999)
900-999 Experimental, vendor-specific, or implementation-defined
opcodes. These MUST NOT be used in interoperable
deployments and MUST NOT be relied upon in Internet-scale
deployments.
Appendix B. Authentication Mechanism Registry
MWS supports a mechanism-agnostic authentication model. During the
initial handshake, the server advertises one or more authentication
mechanisms using MWS_AUTH_CHALLENGE (type=002). The portal selects a
mechanism and responds with MWS_AUTH_RESPONSE (type=003), providing
mechanism-specific credentials or authentication data.
This appendix defines the registry of authentication mechanism
identifiers. Mechanism identifiers are UTF-8 strings and are compared
using case-sensitive bytewise comparison. Identifiers MUST NOT exceed
64 bytes in length.
Implementations MUST ignore unknown mechanism identifiers and MUST
NOT attempt to interpret their payloads. Servers MUST NOT advertise
mechanisms they do not fully support.
B.1. Standard Mechanisms
The following mechanism identifiers are defined by this
specification:
"PAM" The server authenticates the user using the system's
Pluggable Authentication Modules (PAM) stack. The credential
payload contains a NUL-terminated UTF-8 username followed by a
NUL-terminated UTF-8 password, with no trailing octets. This is an
explicit exception to the length-prefixed text convention. The
username MUST be non-empty. A password MAY be empty if local
policy permits it. This mechanism supports one username/password
exchange, not arbitrary interactive PAM conversations. The Server
MUST reject authentication requiring unsupported additional steps.
PAM relies on server-authenticated DTLS confidentiality; a
malicious Portal or Server can observe and reuse the password.
"SSHKEY" The Portal proves possession of an SSH private key whose
public key is authorised for the requested user. The private key
is never transmitted. OpenSSH key files and authorized_keys files
MAY be used as local storage formats; those formats do not form
part of the MWS wire protocol.
The SSHKEY credential has the following format:
username_len 1-octet unsigned integer
username username_len octets
algorithm_len 1-octet unsigned integer
algorithm algorithm_len octets
public_key_len 2-octet unsigned integer
public_key public_key_len octets
signature_len 2-octet unsigned integer
signature signature_len octets
Length fields are in network byte order where they occupy more
than one octet. Strings are UTF-8 and are not NUL-terminated.
Every length MUST be non-zero, and the credential MUST contain
exactly the declared fields with no trailing octets.
algorithm identifies the SSH signature algorithm. This
specification defines ssh-ed25519 [RFC8709], rsa-sha2-256, and
rsa-sha2-512 [RFC8332]. The public_key field contains an SSH
public-key blob: ssh-ed25519 for an Ed25519 key or ssh-rsa for
an RSA key. The signature field is an SSH signature blob
containing the same signature algorithm identifier and the
signature octets. SSH string and public-key encodings follow
[RFC4251] and [RFC4253], with the algorithm-specific formats in
[RFC8709] and [RFC8332]. These inner SSH strings retain their
four-octet lengths; the outer MWS lengths above do not replace
them.
The Portal and server independently obtain the 32-octet
tls-exporter channel binding for the current DTLS association
as defined by [RFC9266]. The Portal signs the following byte
string:
domain_len 1-octet unsigned integer
domain domain_len octets
username_len 1-octet unsigned integer
username username_len octets
channel_binding_len 1-octet unsigned integer
channel_binding channel_binding_len octets
domain is the ASCII string "MWS-SSHKEY", without a terminating
NUL, and channel_binding_len is 32. The username fields MUST be
identical to those in the credential. The server MUST construct
this byte string from the received username and its own channel
binding; it MUST NOT accept a signing envelope supplied by the
Portal.
The server authenticates the user only if the public key is
authorised for username and the signature verifies over this
exact byte string. A malformed credential, an algorithm
mismatch, an unauthorised key, or an invalid signature fails
authentication.
B.2. Extensible Mechanisms
The following identifiers are reserved for future specifications or
external standards. Their payload formats are not defined by this
document.
"FIDO2" Authentication using a FIDO2 authenticator.
"WEBAUTHN" Authentication using a WebAuthn ceremony.
"KERBEROS" Authentication using a Kerberos AP-REQ exchange.
"OAUTH2" Authentication using an OAuth 2.0 device or
authorisation-code flow.
A reserved mechanism MUST NOT be advertised or selected until an
applicable specification defines its payload and authentication
semantics. Implementations MUST NOT guess an encoding from its name.
B.3. Private and Experimental Mechanisms
Mechanism identifiers beginning with the prefix "X-" are reserved for
private, experimental, or vendor-specific use. These identifiers MUST
NOT appear in interoperable deployments or Internet-facing services.
Examples: "X-FINGERPRINT" "X-HARDWARE-TOKEN" "X-SSO-PROTOTYPE"
B.4. Registration Policy
New mechanism identifiers MAY be defined by future MWS extensions or
external standards. To avoid collisions, new identifiers must be
documented by an extension specifying their payload, security
properties, and allocation. This document creates no IANA registry
for authentication mechanisms (Section 10).
Until such time, implementers SHOULD use the "X-" prefix for
experimental mechanisms and MUST NOT assume global uniqueness.
Appendix C. SCTP Stream Usage Summary
MWS uses multiple SCTP streams to isolate control, rendering, input,
video, audio and bulk traffic. This appendix summarises the required
stream assignments. All Portal-association streams use DTLS for
confidentiality and integrity.
Stream assignments are fixed and MUST NOT be repurposed for other
message classes. Implementations MAY open additional streams for
experimental or vendor-specific extensions, provided they do not
conflict with the assignments below.
C.1. Stream 0 -- Control Plane
Stream 0 carries all ordered control-plane traffic, including:
* handshake messages (001-099)
* session-management messages (100-199), including
MWS_SESSION_STATUS render-progress control, except
MWS_CLIPBOARD_RESULT (132), which uses Stream 5
* Portal-association Window control Messages (200-299), except
MWS_FOCUS_WINDOW, which uses Stream 2
* Video FORMATS, OPEN and STATUS (500-502)
* error messages (700-799)
Messages on Stream 0 MUST be delivered reliably and in order. A
logical Message larger than max_user_message_size is fragmented by
Transport as defined in Section 5.1.1.
C.2. Stream 1 -- Rendering Messages
Stream 1 carries Portal-association rendering Messages, currently
MWS_RENDER_PRESENT, MWS_RENDER_SYNC, and MWS_RENDER_DESTROY.
MWS_RENDER_UPLOAD and MWS_RENDER_DAMAGE are client-channel Messages
and MUST NOT be sent on an SCTP Portal association.
Portal-association rendering Messages travel from server to Portal.
MWS_RENDER_FENCE is reserved and MUST NOT be sent by implementations
of this version.
Messages on Stream 1 MUST be delivered reliably and in order. A
logical Message larger than max_user_message_size is fragmented by
Transport as defined in Section 5.1.1.
C.3. Stream 2 -- Input Plane
Stream 2 carries Input Plane Messages (400-499) and MWS_FOCUS_WINDOW
(207) in both directions.
Delivery semantics depend on the Message and event class as specified
in Section 5.4: state transitions and pointer-mode requests are
reliable and ordered, while superseded motion may be coalesced only
where doing so preserves intervening state.
C.4. Stream 3 -- Video Plane
Stream 3 carries MWS_VIDEO_DATA (503) and MWS_VIDEO_CLOSE (504)
reliably and in order. MWS_VIDEO_FORMATS (500), MWS_VIDEO_OPEN (501)
and MWS_VIDEO_STATUS (502) use Control to establish native Window
readiness and report retirement independently of queued encoded data.
Section 5.5 defines flow control.
C.5. Stream 4 -- Audio Plane
Stream 4 carries Audio Messages (600-699). Playback and capture
streams use Session-unique stream_id values and the lifecycles
specified in Section 5.6. This revision defines both payload families
as ordered linear PCM. Later Audio Plane definitions MUST state any
additional loss, buffering and flow-control semantics.
C.6. Stream 5 -- Bulk
Stream 5 carries every MWS_CLIPBOARD_RESULT (132), including format
enumeration, failure and empty-data replies. It is a traffic class
with no minimum payload size. Messages MUST be delivered reliably
and in order. Offers, requests and cancellation remain on Control.
Future assignments to bulk MUST define their own bounded admission
and flow control. Stream separation does not remove shared path
bandwidth, congestion control or socket-buffer limits.
Bulk MUST have lower scheduling priority than Control, Input, Audio,
Render and Video, both at sender admission and native scheduling
where supported. Bulk processing MUST NOT block those other classes.
C.7. Additional Streams
Streams 6-15 are reserved for future standard extensions. Such
extensions MUST specify:
* reliability requirements (reliable, PR-SCTP, unordered)
* congestion-control expectations
* interaction with the control plane
Experimental or vendor-specific extensions SHOULD use streams >=16 to
avoid collision with future standardised assignments.
Appendix D. Protocol State Machine Diagrams
This appendix provides normative state-machine diagrams for the MWS
protocol. These diagrams illustrate the ordered interactions between
portal and server during initial connection, session resumption, and
normal operation. All Portal-association control-plane transitions
occur on SCTP Stream 0. Portal-association rendering, input, video,
audio and bulk traffic occur on their respective streams as defined
in Appendix C.
D.1. Initial Connection State Machine
+------------------+
| TRANSPORT_UP |
+------------------+
|
| MWS_QUERY (001)
| MWS_AUTH_CHALLENGE (002)
| MWS_AUTH_RESPONSE (003)
v
+------------------+
| AUTH_VERIFY |
+------------------+
|
| failure -> fatal error and association loss
| success -> two-way MWS_SESSION_INFO (004)
v
+------------------+
| BOOTSTRAP_ACTIVE |
+------------------+
|
| MWS_SESSION_RESUME_OFFER (100)
v
+-------------------+
| SESSION_SELECTION |
+-------------------+
|
+-------------------------+
| |
| NEW_REQUEST (104) | RESUME_REQUEST (101)
v v
+------------------+ +------------------+
| ACTIVE_SESSION | | RESUME_VERIFY |
+------------------+ +------------------+
| |
| | follow Appendix D.2
| | through reconstruction
| | and RESUME_COMPLETE (102)
| v
| +------------------+
| | ACTIVE_SESSION |
| +------------------+
| |
+------------+------------+
|
| normal Session traffic;
| encoded Video DATA/CLOSE on Stream 3
v
+------------------+
| RUNNING |
+------------------+
NEW_REQUEST and RESUME_REQUEST denote MWS_SESSION_NEW_REQUEST and
MWS_SESSION_RESUME_REQUEST. A rejected resume request returns to
Session selection as specified in Appendix D.2.
D.2. Session Resume State Machine
+------------------+
| RESUME_OFFERED |
+------------------+
|
| MWS_SESSION_RESUME_REQUEST (101)
v
+------------------+
| RESUME_VERIFY |
+------------------+
|
| failure -> MWS_ERROR_SESSION (702, fatal=0),
| return to RESUME_OFFERED
| success -> reserve Session
v
+------------------+
| RESUME_PENDING |
+------------------+
|
| server MWS_SESSION_INFO (004)
| Portal MWS_SESSION_INFO (004)
| MWS_SESSION_STATE_BEGIN (105)
| Window snapshot (Section 5.2.2.1)
| MWS_SESSION_RESUME_COMPLETE (102)
v
+------------------+
| ACTIVE_SESSION |
+------------------+
|
| normal operation resumes:
| * Portal-association rendering on Stream 1
| * input on Stream 2
| * encoded Video DATA and CLOSE on Stream 3
| * audio on Stream 4
| * bulk on Stream 5
v
+------------------+
| RUNNING |
+------------------+
D.3. Error Handling State Machine
Errors may occur at any point in the protocol. The following diagram
illustrates the error-handling model:
+------------------+
| ANY_STATE |
+------------------+
|
| recoverable error
| MWS_ERROR_* (700-705, fatal=0)
v
+------------------+
| CONTINUE |
+------------------+
|
| fatal error
| MWS_ERROR_* (700-705, fatal=1)
v
+------------------+
| TERMINATE |
+------------------+
|
| SCTP association closed
v
+------------------+
| END |
+------------------+
D.4. Stream Interaction Summary
The following summary illustrates the concurrency model across SCTP
streams:
Stream 0 (control): ordered, reliable
* handshake (001-099)
* session management (100-199), except MWS_CLIPBOARD_RESULT (132)
* Window control (200-299), except MWS_FOCUS_WINDOW (207)
* Video FORMATS, OPEN and STATUS (500-502)
* error reporting (700-799)
Stream 1 (rendering): ordered, reliable
* MWS_RENDER_PRESENT, MWS_RENDER_SYNC and MWS_RENDER_DESTROY
Stream 2 (input): delivery policy depends on event class
* input Messages (400-499) and MWS_FOCUS_WINDOW (207)
Stream 3 (video): ordered, reliable
* encoded Video DATA and CLOSE (503-504)
Stream 4 (audio): ordered, reliable PCM
* audio Messages (600-699)
Stream 5 (bulk): ordered, reliable, lowest priority
* all MWS_CLIPBOARD_RESULT (132) replies, regardless of size
These streams have independent delivery ordering and the scheduling
priorities defined in Section 4.7. Implementations MUST NOT impose a
shared application processing queue that blocks control behind work
on any non-control stream. SCTP congestion control and shared network
capacity can still delay more than one stream.
Author's Address
Christopher Ross
Independent
Email: chris@tebibyte.org
Project Website: https://mercurius.tebibyte.org
This Internet-Draft will expire on 21 May 2027.