unom/punktfunk
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases 4 Wiki Activity

feat(host/library): game library API — Steam adapter + custom store
ci / web (push) Successful in 28s
Details
ci / docs-site (push) Successful in 30s
Details
apple / swift (push) Successful in 1m15s
Details
ci / bench (push) Successful in 1m35s
Details
ci / rust (push) Successful in 2m7s
Details
docker / build-push (--build-arg FEDORA_VERSION=44, ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm) (push) Successful in 6s
Details
docker / build-push (., web/Dockerfile, punktfunk-web) (push) Successful in 15s
Details
docker / build-push (ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Successful in 3s
Details
docker / build-push (ci, ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Successful in 5s
Details
docker / build-push (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Successful in 4s
Details
deb / build-publish (push) Successful in 2m19s
Details
rpm / build-publish (bazzite, punktfunk-fedora-rpm) (push) Successful in 4m53s
Details
docker / deploy-docs (push) Successful in 18s
Details
rpm / build-publish (fedora-44, punktfunk-fedora44-rpm) (push) Successful in 4m31s
Details

Browse Source 
A new `library` module + four mgmt endpoints surface the host's games to clients
(plan: "surface the user's games"). An adapter layer (`LibraryProvider`) so future
stores (Heroic/Epic, GOG, Lutris) slot in behind one uniform `GameEntry`.

- SteamProvider: reads the LOCAL Steam install — no Steam Web API key, no network.
  Installed titles from steamapps/appmanifest_<appid>.acf; extra library folders
  (incl. paths with spaces) from libraryfolders.vdf; candidate roots cover classic,
  Flatpak and Deck layouts, canonicalized + deduped (the .steam/{steam,root}
  symlinks all fold to one). Runtimes/redistributables (Proton, Steam Linux Runtime,
  Steamworks Common, SteamVR) filtered out. Artwork = the public Steam CDN by appid
  (portrait/hero/logo/header), fetched directly by the client.
- Custom store: ~/.config/punktfunk/library.json, write-then-rename persisted,
  CRUD'd via the API — the "create custom entries via the admin web UI" requirement.
- API (under /api/v1, OpenAPI-documented + checked in): GET /library (all stores
  merged, sorted), POST /library/custom, PUT/DELETE /library/custom/{id}.
- `punktfunk-host library` subcommand dumps the resolved library as JSON (diagnostic,
  mirrors `openapi`).

Validated live against the real Steam library on the Bazzite box: 89 appmanifests →
78 games (11 tools filtered), correct titles/sort, and the CDN art URLs return 200.
5 unit tests for the VDF/ACF parsing, tool filter, art URLs, custom mapping.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Enrico Bühler
2026-06-14 13:43:03 +00:00
parent ee7984beb0
commit 6351d516e0
4 changed files with 932 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/openapi.json
+383
View File
@@ -194,6 +194,238 @@
}
}
},
"/api/v1/library": {
"get": {
"tags": [
"library"
],
"summary": "List the game library",
"description": "Every installed-store title (Steam, read from the host's local files — no Steam API key)\nmerged with the user's custom entries, sorted by title. Artwork fields are URLs the client\nfetches directly (the public Steam CDN for Steam titles).",
"operationId": "getLibrary",
"responses": {
"200": {
"description": "Unified library across all stores",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GameEntry"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/library/custom": {
"post": {
"tags": [
"library"
],
"summary": "Add a custom library entry",
"description": "Creates a user-curated title (e.g. a non-Steam game, an emulator, a ROM) with caller-supplied\nartwork URLs. The host assigns a stable id, returned in the body.",
"operationId": "createCustomGame",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomInput"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Entry created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomEntry"
}
}
}
},
"400": {
"description": "Empty title",
"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": "Could not persist the catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/library/custom/{id}": {
"put": {
"tags": [
"library"
],
"summary": "Update a custom library entry",
"operationId": "updateCustomGame",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The custom entry id (without the `custom:` prefix)",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomInput"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Entry updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomEntry"
}
}
}
},
"400": {
"description": "Empty title",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No custom entry with that id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not persist the catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
},
"delete": {
"tags": [
"library"
],
"summary": "Delete a custom library entry",
"operationId": "deleteCustomGame",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The custom entry id (without the `custom:` prefix)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Entry deleted"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No custom entry with that id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not persist the catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/native/clients": {
"get": {
"tags": [
@@ -831,6 +1063,40 @@
}
}
},
"Artwork": {
"type": "object",
"description": "Cover art for a title. All fields are URLs (the Steam CDN for Steam titles, user-supplied for\ncustom). The client prefers `portrait` for a grid and falls back to `header` when a title has\nno 600×900 capsule (common for older Steam apps).",
"properties": {
"header": {
"type": [
"string",
"null"
],
"description": "Horizontal header (Steam `header.jpg`) — the universal fallback."
},
"hero": {
"type": [
"string",
"null"
],
"description": "Wide background (Steam `library_hero.jpg`)."
},
"logo": {
"type": [
"string",
"null"
],
"description": "Transparent title logo (Steam `logo.png`)."
},
"portrait": {
"type": [
"string",
"null"
],
"description": "Vertical capsule / poster (Steam `library_600x900.jpg`). Best for a grid."
}
}
},
"AvailableCompositor": {
"type": "object",
"description": "A compositor backend the host can drive a virtual output on, and whether it's usable now.",
@@ -859,6 +1125,100 @@
}
}
},
"CustomEntry": {
"type": "object",
"description": "A user-added title, persisted in `~/.config/punktfunk/library.json`. Same shape the API\nreturns and the web console edits.",
"required": [
"id",
"title"
],
"properties": {
"art": {
"$ref": "#/components/schemas/Artwork"
},
"id": {
"type": "string",
"description": "Host-assigned, stable for the life of the entry (the `{id}` in the CRUD path)."
},
"launch": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/LaunchSpec"
}
]
},
"title": {
"type": "string"
}
}
},
"CustomInput": {
"type": "object",
"description": "Request body to create or replace a custom entry (no `id` — the host owns it).",
"required": [
"title"
],
"properties": {
"art": {
"$ref": "#/components/schemas/Artwork"
},
"launch": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/LaunchSpec"
}
]
},
"title": {
"type": "string"
}
}
},
"GameEntry": {
"type": "object",
"description": "One title in the unified library, regardless of which store it came from.",
"required": [
"id",
"store",
"title",
"art"
],
"properties": {
"art": {
"$ref": "#/components/schemas/Artwork"
},
"id": {
"type": "string",
"description": "Stable, store-qualified id: `steam:<appid>` or `custom:<id>`.",
"example": "steam:570"
},
"launch": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/LaunchSpec",
"description": "How the host would launch it, when known."
}
]
},
"store": {
"type": "string",
"description": "Which store surfaced it: `\"steam\"` or `\"custom\"`.",
"example": "steam"
},
"title": {
"type": "string"
}
}
},
"Health": {
"type": "object",
"description": "Liveness + version probe.",
@@ -941,6 +1301,25 @@
}
}
},
"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.",
"required": [
"kind",
"value"
],
"properties": {
"kind": {
"type": "string",
"description": "`\"steam_appid\"` or `\"command\"`.",
"example": "steam_appid"
},
"value": {
"type": "string",
"description": "The appid (for `steam_appid`) or the shell command (for `command`)."
}
}
},
"NativeClient": {
"type": "object",
"description": "A paired native (punktfunk/1) client.",
@@ -1313,6 +1692,10 @@
{
"name": "session",
"description": "Active streaming session control"
},
{
"name": "library",
"description": "Game library: installed-store titles (Steam) plus user-curated custom entries"
}
]
}