@xiboplayer/proxy

CORS proxy and static server for xiboplayer shells.

Overview

Shared Express server used by all XiboPlayer shells (Electron, Chromium kiosk, standalone):

• XMDS Proxy — forwards SOAP/XML requests to the CMS (/xmds-proxy)
• REST Proxy — forwards REST API requests (/rest-proxy)
• File Proxy — downloads media files with Range support (/file-proxy)
• PWA Server — serves the PWA player as static files (/player/pwa/)

Installation

npm install @xiboplayer/proxy

Usage

As a library

import { createProxyApp, startServer } from '@xiboplayer/proxy';

// Option 1: get the Express app (for embedding in Electron, etc.)
const app = createProxyApp({
  pwaPath: '/path/to/pwa/dist',
  appVersion: '1.0.0',
});
app.listen(8765, 'localhost');

// Option 2: start a standalone server
const { server, port } = await startServer({
  port: 8765,
  pwaPath: '/path/to/pwa/dist',
  appVersion: '1.0.0',
});

As a CLI

npx xiboplayer-proxy --pwa-path=../xiboplayer-pwa/dist --port=8765

API Reference

createProxyApp({ pwaPath, appVersion })

Returns a configured Express app with all proxy routes and static PWA serving.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | pwaPath | string | (required) | Absolute path to PWA dist directory | | appVersion | string | '0.0.0' | Version for User-Agent header |

startServer({ port, pwaPath, appVersion })

Creates the app and starts listening. Returns Promise<{ server, port }>.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | port | number | 8765 | Port to listen on | | pwaPath | string | (required) | Absolute path to PWA dist directory | | appVersion | string | '0.0.0' | Version for User-Agent header | | syncGroupId | string | — | Sync group ID for mDNS advertisement (lead only) | | isLead | boolean | — | Whether to advertise via mDNS on startup | | displayId | string | — | Display hardware key for mDNS TXT record | | syncSecret | string | — | Shared secret for WebSocket relay auth |

Proxy Routes

| Route | Method | Description | |-------|--------|-------------| | /xmds-proxy?cms=URL | ALL | Proxies XMDS SOAP requests to URL/xmds.php | | /api/* | ALL | Forward proxy to CMS REST API (injects JWT Bearer token) | | /player/ | GET | Serves PWA index.html with config injection |

System Routes (v0.7.1)

| Route | Method | Description | |-------|--------|-------------| | /system/lan-ip | GET | Returns { ip } — machine's LAN IPv4 address | | /system/discover-lead | GET | mDNS browse for sync lead. Query: syncGroupId. Returns { host, port } or 404 | | /system/advertise-sync | POST | Start mDNS advertisement. Body: { syncGroupId, port, displayId } |

ContentStore Routes

| Route | Method | Description | |-------|--------|-------------| | /store/:type/* | HEAD | Existence + size check (404 for incomplete chunked files) | | /store/:type/* | GET | Serve stored file with Range support | | /store/:type/* | PUT | Store file content | | /store/delete | POST | Delete files from store | | /store/mark-complete | POST | Mark chunked download as complete | | /store/unmark-complete | POST | Unmark chunked file (keeps chunks on disk for partial re-download) | | /store/missing-chunks/:type/* | GET | Return { missing: number[], numChunks: number } for a chunked file | | /store/list | GET | List all stored files with metadata |

Cache-Through Mirror Routes

| Route | Method | Description | |-------|--------|-------------| | /api/v2/player/media/:id | GET/HEAD | Media files (images, video, audio, XLF) | | /api/v2/player/layouts/:id | GET/HEAD | Layout XLF files | | /api/v2/player/widgets/:l/:r/:m | GET/HEAD | Widget HTML | | /api/v2/player/dependencies/* | GET/HEAD | Static resources (CSS, fonts, JS) | | /api/v2/player/datasets/:id/data | GET | Dataset data (JSON, no caching) |

Dependencies

• express — HTTP server
• cors — CORS middleware
• bonjour-service — mDNS/DNS-SD for sync discovery
• ws — WebSocket server for sync relay

xiboplayer.org · Part of the XiboPlayer SDK