feat(vdisplay): display-management policy surface (Stage 0)
A user-configurable policy layer above the per-compositor VirtualDisplay backends: keep-alive, topology, conflict, identity, layout, max-displays — persisted to display-settings.json, editable from the web console, applied per connect. Design: design/display-management.md. Stage 0 stands up the surface and wires the two behaviors the existing code can already express — the Windows monitor linger duration and the "make the streamed output the sole desktop" topology — through it; every other option is stored + echoed but not yet enforced (later stages). An unconfigured host (no display-settings.json) keeps today's exact behavior. - vdisplay/policy.rs: pure DisplayPolicy + 5 presets + JSON store (gpu-settings pattern) + EffectivePolicy; 9 unit tests. - vdisplay.rs: resolve_topology(Auto); apply_session_env drives *_VIRTUAL_PRIMARY from the policy only when a settings file exists. - windows/manager.rs: linger_ms() + should_isolate() read the policy when configured. - mgmt: GET/PUT /api/v1/display/settings (bearer-only); PUT rejects keep_alive forever until the lifecycle stage. OpenAPI regenerated. - web console: Host → Virtual displays card (preset picker + custom fields); en+de. - docs-site: virtual-displays.md + configuration.md cross-links. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
+371
-1
@@ -10,7 +10,7 @@
|
||||
"name": "MIT OR Apache-2.0",
|
||||
"identifier": "MIT OR Apache-2.0"
|
||||
},
|
||||
"version": "0.6.0"
|
||||
"version": "0.7.4"
|
||||
},
|
||||
"paths": {
|
||||
"/api/v1/clients": {
|
||||
@@ -138,6 +138,98 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/display/settings": {
|
||||
"get": {
|
||||
"tags": [
|
||||
"display"
|
||||
],
|
||||
"summary": "Display-management policy",
|
||||
"description": "The stored virtual-display policy (lifecycle, topology, conflict handling, identity, layout),\nevery preset's expansion, and which options this build enforces yet. See\n`design/display-management.md`.",
|
||||
"operationId": "getDisplaySettings",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Stored policy + preset expansions + enforced options",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/DisplaySettingsState"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Missing or invalid bearer token",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ApiError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"put": {
|
||||
"tags": [
|
||||
"display"
|
||||
],
|
||||
"summary": "Set the display-management policy",
|
||||
"description": "Persists a new policy (validated + clamped) and applies it from the next connect/teardown — a\nrunning session keeps the display it opened on. `keep_alive: forever` is rejected until the\ndisplay-lifecycle stage ships (it would keep physical monitors dark indefinitely with no release\npath yet).",
|
||||
"operationId": "setDisplaySettings",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/DisplayPolicy"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": true
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Policy stored; the new state",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/DisplaySettingsState"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "An option value is not yet supported (e.g. keep_alive forever)",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ApiError"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Missing or invalid bearer token",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ApiError"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Policy could not be persisted",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ApiError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/gpus": {
|
||||
"get": {
|
||||
"tags": [
|
||||
@@ -1909,6 +2001,115 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"DisplayPolicy": {
|
||||
"type": "object",
|
||||
"description": "The user-facing display-management policy — what `display-settings.json` holds and what the mgmt\nAPI GETs/PUTs. When [`preset`](Self::preset) is not [`Preset::Custom`] the explicit fields are\nignored (the console writes one or the other); [`effective`](Self::effective) resolves both to a\nsingle [`EffectivePolicy`].",
|
||||
"properties": {
|
||||
"identity": {
|
||||
"$ref": "#/components/schemas/Identity"
|
||||
},
|
||||
"keep_alive": {
|
||||
"$ref": "#/components/schemas/KeepAlive"
|
||||
},
|
||||
"layout": {
|
||||
"$ref": "#/components/schemas/Layout"
|
||||
},
|
||||
"max_displays": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"description": "Upper bound on simultaneously-live virtual displays (clamped to `1..=16` on write).",
|
||||
"minimum": 0
|
||||
},
|
||||
"mode_conflict": {
|
||||
"$ref": "#/components/schemas/ModeConflict"
|
||||
},
|
||||
"preset": {
|
||||
"$ref": "#/components/schemas/Preset"
|
||||
},
|
||||
"topology": {
|
||||
"$ref": "#/components/schemas/Topology"
|
||||
},
|
||||
"version": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"description": "Schema version (currently 1) — lets a future field addition migrate rather than reject.",
|
||||
"minimum": 0
|
||||
}
|
||||
}
|
||||
},
|
||||
"DisplaySettingsState": {
|
||||
"type": "object",
|
||||
"description": "Full display-management state for the console: the stored policy, every preset's expansion, the\nresolved effective policy, and which options this build actually enforces yet (Stage 0 wires\nkeep-alive linger + topology; the rest are stored but not yet acted on).",
|
||||
"required": [
|
||||
"settings",
|
||||
"configured",
|
||||
"effective",
|
||||
"presets",
|
||||
"enforced"
|
||||
],
|
||||
"properties": {
|
||||
"configured": {
|
||||
"type": "boolean",
|
||||
"description": "True once a `display-settings.json` exists (the console has configured this host)."
|
||||
},
|
||||
"effective": {
|
||||
"$ref": "#/components/schemas/EffectivePolicy",
|
||||
"description": "The effective (preset-expanded) policy currently in force."
|
||||
},
|
||||
"enforced": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Option names this build enforces right now (e.g. `keep_alive`, `topology`). The remaining\nstored options (`mode_conflict`, `identity`, `layout`) land in later stages — surfaced so the\nconsole can mark them \"coming soon\" instead of implying they already take effect."
|
||||
},
|
||||
"presets": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/PresetInfo"
|
||||
},
|
||||
"description": "Every named preset and what it expands to (for the picker's preview)."
|
||||
},
|
||||
"settings": {
|
||||
"$ref": "#/components/schemas/DisplayPolicy",
|
||||
"description": "The stored policy (preset + custom fields), or the built-in default when unconfigured."
|
||||
}
|
||||
}
|
||||
},
|
||||
"EffectivePolicy": {
|
||||
"type": "object",
|
||||
"description": "The six resolved fields after preset expansion — what the lifecycle/registry and the Stage-0 call\nsites read, and what the mgmt API echoes as the \"currently in force\" policy. Pure output of\n[`DisplayPolicy::effective`].",
|
||||
"required": [
|
||||
"keep_alive",
|
||||
"topology",
|
||||
"mode_conflict",
|
||||
"identity",
|
||||
"layout",
|
||||
"max_displays"
|
||||
],
|
||||
"properties": {
|
||||
"identity": {
|
||||
"$ref": "#/components/schemas/Identity"
|
||||
},
|
||||
"keep_alive": {
|
||||
"$ref": "#/components/schemas/KeepAlive"
|
||||
},
|
||||
"layout": {
|
||||
"$ref": "#/components/schemas/Layout"
|
||||
},
|
||||
"max_displays": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"minimum": 0
|
||||
},
|
||||
"mode_conflict": {
|
||||
"$ref": "#/components/schemas/ModeConflict"
|
||||
},
|
||||
"topology": {
|
||||
"$ref": "#/components/schemas/Topology"
|
||||
}
|
||||
}
|
||||
},
|
||||
"GameEntry": {
|
||||
"type": "object",
|
||||
"description": "One title in the unified library, regardless of which store it came from.",
|
||||
@@ -2099,6 +2300,72 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"Identity": {
|
||||
"type": "string",
|
||||
"description": "Stable display identity, so desktop environments persist per-display config (KDE scaling). Stored\nat Stage 0; carriers wired from the identity stage.",
|
||||
"enum": [
|
||||
"shared",
|
||||
"per-client",
|
||||
"per-client-mode"
|
||||
]
|
||||
},
|
||||
"KeepAlive": {
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Tear the display down at session end (today's default on every backend but Windows, which\nlingers 10 s).",
|
||||
"required": [
|
||||
"mode"
|
||||
],
|
||||
"properties": {
|
||||
"mode": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"off"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Keep the display for `seconds` after the last session leaves, then tear it down; a reconnect\ninside the window reuses it.",
|
||||
"required": [
|
||||
"seconds",
|
||||
"mode"
|
||||
],
|
||||
"properties": {
|
||||
"mode": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"duration"
|
||||
]
|
||||
},
|
||||
"seconds": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"description": "Linger window in seconds.",
|
||||
"minimum": 0
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Keep the display until host shutdown or an explicit release (the `Pinned` lifecycle state).\n**Not honored until the display-lifecycle stage** — rejected by the mgmt PUT at Stage 0.",
|
||||
"required": [
|
||||
"mode"
|
||||
],
|
||||
"properties": {
|
||||
"mode": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"forever"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"description": "How long a virtual display (and, on gamescope's bare spawn, the nested session + its game)\nsurvives after the last client session detaches. Serialized as an object tagged on `mode`\n(`{\"mode\":\"off\"}` / `{\"mode\":\"duration\",\"seconds\":300}` / `{\"mode\":\"forever\"}`) so the web form\nand the OpenAPI schema stay simple."
|
||||
},
|
||||
"LaunchSpec": {
|
||||
"type": "object",
|
||||
"description": "How the host would launch a title (consumed by the session launcher in a later step). Kept\nopen-ended so new stores slot in: `steam_appid` → `steam steam://rungameid/<value>`;\n`command` → run `<value>` nested in a gamescope session.",
|
||||
@@ -2118,6 +2385,32 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"Layout": {
|
||||
"type": "object",
|
||||
"description": "Group layout: the arrangement mode plus, for [`LayoutMode::Manual`], per-slot offsets keyed by\nidentity-slot id (string keys for stable JSON).",
|
||||
"properties": {
|
||||
"mode": {
|
||||
"$ref": "#/components/schemas/LayoutMode"
|
||||
},
|
||||
"positions": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"$ref": "#/components/schemas/Position"
|
||||
},
|
||||
"propertyNames": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"LayoutMode": {
|
||||
"type": "string",
|
||||
"description": "How group members are arranged in the desktop coordinate space. Stored at Stage 0; applied from\nthe multi-monitor stage.",
|
||||
"enum": [
|
||||
"auto-row",
|
||||
"manual"
|
||||
]
|
||||
},
|
||||
"LocalSummary": {
|
||||
"type": "object",
|
||||
"description": "Non-sensitive host status for the local tray icon: counts and booleans only — no PIN values,\nno fingerprints, no device names. Served unauthenticated to LOOPBACK peers only (see\n`require_auth`): the bearer-token file is SYSTEM/Administrators-DACL'd on Windows, so the\nper-user tray process cannot authenticate — this narrow read-only route is its status source.",
|
||||
@@ -2242,6 +2535,16 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"ModeConflict": {
|
||||
"type": "string",
|
||||
"description": "Admission when a *different* client connects while a display/session is already live and asks for\na different mode. Stored at Stage 0; enforced from the mode-conflict admission stage.",
|
||||
"enum": [
|
||||
"separate",
|
||||
"steal",
|
||||
"join",
|
||||
"reject"
|
||||
]
|
||||
},
|
||||
"NativeClient": {
|
||||
"type": "object",
|
||||
"description": "A paired native (punktfunk/1) client.",
|
||||
@@ -2439,6 +2742,59 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"Position": {
|
||||
"type": "object",
|
||||
"description": "A desktop-space offset for a display (top-left origin).",
|
||||
"required": [
|
||||
"x",
|
||||
"y"
|
||||
],
|
||||
"properties": {
|
||||
"x": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
},
|
||||
"y": {
|
||||
"type": "integer",
|
||||
"format": "int32"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Preset": {
|
||||
"type": "string",
|
||||
"description": "A named bundle of the fields below. `Custom` (the default) means the explicit fields rule; any\nother preset ignores the stored fields and expands to its own ([`DisplayPolicy::effective`]).",
|
||||
"enum": [
|
||||
"custom",
|
||||
"default",
|
||||
"gaming-rig",
|
||||
"shared-desktop",
|
||||
"hotdesk",
|
||||
"workstation"
|
||||
]
|
||||
},
|
||||
"PresetInfo": {
|
||||
"type": "object",
|
||||
"description": "One preset's human-facing description + the fields it expands to, so the console can render a\npreset picker with an accurate \"what this does\" preview without hardcoding the expansion.",
|
||||
"required": [
|
||||
"id",
|
||||
"summary",
|
||||
"fields"
|
||||
],
|
||||
"properties": {
|
||||
"fields": {
|
||||
"$ref": "#/components/schemas/EffectivePolicy",
|
||||
"description": "The effective policy this preset expands to (the same fields a `custom` policy carries)."
|
||||
},
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "The preset id (`default` | `gaming-rig` | `shared-desktop` | `hotdesk` | `workstation`)."
|
||||
},
|
||||
"summary": {
|
||||
"type": "string",
|
||||
"description": "One-line story shown next to the option."
|
||||
}
|
||||
}
|
||||
},
|
||||
"RuntimeStatus": {
|
||||
"type": "object",
|
||||
"description": "Live host status (changes as clients launch/end sessions).",
|
||||
@@ -2740,6 +3096,16 @@
|
||||
"example": "1234"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Topology": {
|
||||
"type": "string",
|
||||
"description": "What the host does to the box's display topology while managed virtual displays are up.",
|
||||
"enum": [
|
||||
"auto",
|
||||
"extend",
|
||||
"primary",
|
||||
"exclusive"
|
||||
]
|
||||
}
|
||||
},
|
||||
"securitySchemes": {
|
||||
@@ -2763,6 +3129,10 @@
|
||||
"name": "gpu",
|
||||
"description": "GPU inventory and selection: list the host's GPUs, choose automatic or a preferred GPU, see the one in use"
|
||||
},
|
||||
{
|
||||
"name": "display",
|
||||
"description": "Virtual-display management policy: lifecycle (keep-alive), topology (primary/exclusive), conflict handling, identity, and layout"
|
||||
},
|
||||
{
|
||||
"name": "clients",
|
||||
"description": "Paired Moonlight client management"
|
||||
|
||||
Reference in New Issue
Block a user