@xiboplayer/proxy 0.2.0

package/README.md

@@ -0,0 +1,86 @@
+# @xiboplayer/proxy
+
+**CORS proxy and static server for Xibo Player 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
+
+```bash
+npm install @xiboplayer/proxy
+```
+
+## Usage
+
+### As a library
+
+```javascript
+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
+
+```bash
+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 |
+
+## Proxy Routes
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/xmds-proxy?cms=URL` | ALL | Proxies XMDS SOAP requests to `URL/xmds.php` |
+| `/rest-proxy?cms=URL&path=/api/...` | ALL | Proxies REST API requests |
+| `/file-proxy?cms=URL&url=/path` | GET | Downloads files (supports Range) |
+| `/player/pwa/` | GET | Serves PWA static files |
+| `/` | GET | Redirects to `/player/pwa/` |
+
+## Dependencies
+
+- `express` — HTTP server
+- `cors` — CORS middleware
+
+---
+
+**Part of the [XiboPlayer SDK](https://github.com/xibo-players/xiboplayer)**

package/bin/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * xiboplayer-proxy CLI — standalone CORS proxy + PWA server
+ *
+ * Usage:
+ *   xiboplayer-proxy --port=8765 --pwa-path=/path/to/pwa/dist
+ *   npx xiboplayer-proxy --pwa-path=../xiboplayer-pwa/dist
+ */
+
+import { startServer } from '../src/proxy.js';
+
+const args = process.argv.slice(2);
+const portArg = args.find(a => a.startsWith('--port='));
+const pwaArg = args.find(a => a.startsWith('--pwa-path='));
+
+const port = portArg ? parseInt(portArg.split('=')[1], 10) : 8765;
+const pwaPath = pwaArg ? pwaArg.split('=')[1] : null;
+
+if (!pwaPath) {
+  console.error('Usage: xiboplayer-proxy --pwa-path=/path/to/pwa/dist [--port=8765]');
+  process.exit(1);
+}
+
+startServer({ port, pwaPath, appVersion: '0.2.0' }).catch((err) => {
+  console.error('Failed to start:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@xiboplayer/proxy",
+  "version": "0.2.0",
+  "description": "CORS proxy and static server for Xibo Player (serves PWA + proxies CMS)",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./cli": "./bin/cli.js"
+  },
+  "bin": {
+    "xiboplayer-proxy": "./bin/cli.js"
+  },
+  "dependencies": {
+    "express": "^5.2.1",
+    "cors": "^2.8.6"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "xibo",
+    "digital-signage",
+    "proxy",
+    "cors",
+    "express"
+  ],
+  "author": "Pau Aliagas <linuxnow@gmail.com>",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xibo-players/xiboplayer.git",
+    "directory": "packages/proxy"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/index.js

@@ -0,0 +1 @@
+export { createProxyApp, startServer } from './proxy.js';

package/src/proxy.js

@@ -0,0 +1,198 @@
+/**
+ * @xiboplayer/proxy — CORS proxy + static server for Xibo Player
+ *
+ * Provides Express middleware that:
+ * - Proxies XMDS SOAP requests (/xmds-proxy)
+ * - Proxies REST API requests (/rest-proxy)
+ * - Proxies file downloads with Range support (/file-proxy)
+ * - Serves the PWA player as static files (/player/pwa/)
+ */
+
+import path from 'path';
+import express from 'express';
+import cors from 'cors';
+
+const SKIP_HEADERS = ['transfer-encoding', 'connection', 'content-encoding', 'content-length'];
+
+/**
+ * Create a configured Express app with CORS proxy routes and PWA static serving.
+ *
+ * @param {object} options
+ * @param {string} options.pwaPath  — absolute path to PWA dist directory
+ * @param {string} [options.appVersion='0.0.0'] — version string for User-Agent header
+ * @returns {import('express').Express}
+ */
+export function createProxyApp({ pwaPath, appVersion = '0.0.0' }) {
+  const app = express();
+
+  app.use(cors({
+    origin: '*',
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'SOAPAction'],
+    credentials: true,
+  }));
+
+  app.use(express.text({ type: 'text/xml', limit: '50mb' }));
+  app.use(express.text({ type: 'application/xml', limit: '50mb' }));
+  app.use(express.json({ limit: '10mb' }));
+  app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+
+  // ─── XMDS SOAP Proxy ──────────────────────────────────────────────
+  app.all('/xmds-proxy', async (req, res) => {
+    try {
+      const cmsUrl = req.query.cms;
+      if (!cmsUrl) return res.status(400).json({ error: 'Missing cms parameter' });
+
+      const queryParams = new URLSearchParams(req.query);
+      queryParams.delete('cms');
+      const queryString = queryParams.toString();
+      const xmdsUrl = `${cmsUrl}/xmds.php${queryString ? '?' + queryString : ''}`;
+
+      console.log(`[Proxy] ${req.method} ${xmdsUrl}`);
+
+      const headers = {
+        'Content-Type': req.headers['content-type'] || 'text/xml; charset=utf-8',
+        'User-Agent': `XiboPlayer/${appVersion}`,
+      };
+      if (req.headers['soapaction']) headers['SOAPAction'] = req.headers['soapaction'];
+
+      const response = await fetch(xmdsUrl, {
+        method: req.method,
+        headers,
+        body: req.method !== 'GET' && req.body ? req.body : undefined,
+      });
+
+      const contentType = response.headers.get('content-type');
+      if (contentType) res.setHeader('Content-Type', contentType);
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      const responseText = await response.text();
+      res.status(response.status).send(responseText);
+      console.log(`[Proxy] ${response.status} (${responseText.length} bytes)`);
+    } catch (error) {
+      console.error('[Proxy] Error:', error.message);
+      res.status(500).json({ error: 'Proxy error', message: error.message });
+    }
+  });
+
+  // ─── REST API Proxy ────────────────────────────────────────────────
+  app.all('/rest-proxy', async (req, res) => {
+    try {
+      const cmsUrl = req.query.cms;
+      const apiPath = req.query.path;
+      if (!cmsUrl) return res.status(400).json({ error: 'Missing cms parameter' });
+
+      const queryParams = new URLSearchParams(req.query);
+      queryParams.delete('cms');
+      queryParams.delete('path');
+      const queryString = queryParams.toString();
+      const fullUrl = `${cmsUrl}${apiPath || ''}${queryString ? '?' + queryString : ''}`;
+
+      console.log(`[REST Proxy] ${req.method} ${fullUrl}`);
+
+      const headers = { 'User-Agent': `XiboPlayer/${appVersion}` };
+      if (req.headers['content-type']) headers['Content-Type'] = req.headers['content-type'];
+      if (req.headers['authorization']) headers['Authorization'] = req.headers['authorization'];
+      if (req.headers['accept']) headers['Accept'] = req.headers['accept'];
+      if (req.headers['if-none-match']) headers['If-None-Match'] = req.headers['if-none-match'];
+
+      const fetchOptions = { method: req.method, headers };
+      if (req.method !== 'GET' && req.method !== 'HEAD' && req.body) {
+        fetchOptions.body = typeof req.body === 'string' ? req.body : JSON.stringify(req.body);
+      }
+
+      const response = await fetch(fullUrl, fetchOptions);
+      response.headers.forEach((value, key) => {
+        if (!SKIP_HEADERS.includes(key.toLowerCase())) {
+          res.setHeader(key, value);
+        }
+      });
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      const buffer = await response.arrayBuffer();
+      res.status(response.status).send(Buffer.from(buffer));
+      console.log(`[REST Proxy] ${response.status} (${buffer.byteLength} bytes)`);
+    } catch (error) {
+      console.error('[REST Proxy] Error:', error.message);
+      res.status(500).json({ error: 'REST proxy error', message: error.message });
+    }
+  });
+
+  // ─── File Download Proxy ───────────────────────────────────────────
+  app.get('/file-proxy', async (req, res) => {
+    try {
+      const cmsUrl = req.query.cms;
+      const fileUrl = req.query.url;
+      if (!cmsUrl || !fileUrl) return res.status(400).json({ error: 'Missing cms or url parameter' });
+
+      const fullUrl = `${cmsUrl}${fileUrl}`;
+      console.log(`[FileProxy] GET ${fullUrl}`);
+
+      const headers = { 'User-Agent': `XiboPlayer/${appVersion}` };
+      if (req.headers.range) {
+        headers['Range'] = req.headers.range;
+        console.log(`[FileProxy] Range: ${req.headers.range}`);
+      }
+
+      const response = await fetch(fullUrl, { headers });
+      res.status(response.status);
+      response.headers.forEach((value, key) => {
+        if (!SKIP_HEADERS.includes(key.toLowerCase())) {
+          res.setHeader(key, value);
+        }
+      });
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      const buffer = await response.arrayBuffer();
+      res.send(Buffer.from(buffer));
+      console.log(`[FileProxy] ${response.status} (${buffer.byteLength} bytes)`);
+    } catch (error) {
+      console.error('[FileProxy] Error:', error.message);
+      res.status(500).json({ error: 'File proxy error', message: error.message });
+    }
+  });
+
+  // ─── Serve PWA static files ────────────────────────────────────────
+  app.use('/player/pwa', express.static(pwaPath, {
+    setHeaders: (res, filePath) => {
+      if (filePath.endsWith('sw-pwa.js')) {
+        res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+        res.setHeader('Service-Worker-Allowed', '/player/pwa/');
+      }
+    },
+  }));
+
+  app.get('/', (req, res) => res.redirect('/player/pwa/'));
+  app.get('/player/pwa/{*splat}', (req, res) => res.sendFile(path.join(pwaPath, 'index.html')));
+
+  return app;
+}
+
+/**
+ * Create the proxy app and start listening.
+ *
+ * @param {object} options
+ * @param {number} [options.port=8765]
+ * @param {string} options.pwaPath
+ * @param {string} [options.appVersion='0.0.0']
+ * @returns {Promise<{ server: import('http').Server, port: number }>}
+ */
+export function startServer({ port = 8765, pwaPath, appVersion = '0.0.0' }) {
+  const app = createProxyApp({ pwaPath, appVersion });
+
+  return new Promise((resolve, reject) => {
+    const server = app.listen(port, 'localhost', () => {
+      console.log(`[Server] Running on http://localhost:${port}`);
+      console.log(`[Server] READY`);
+      resolve({ server, port });
+    });
+
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        console.error(`[Server] Port ${port} already in use. Try --port=XXXX`);
+      }
+      reject(err);
+    });
+
+    // Graceful shutdown
+    process.on('SIGINT', () => { server.close(); process.exit(0); });
+    process.on('SIGTERM', () => { server.close(); process.exit(0); });
+  });
+}

package/src/proxy.test.js

@@ -0,0 +1,88 @@
+// @vitest-environment node
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createProxyApp } from './proxy.js';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+import os from 'os';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Restore real fetch (root vitest.setup.js mocks it with vi.fn())
+const realFetch = global.__nativeFetch || globalThis.fetch;
+
+// Create a temporary PWA directory with a minimal index.html
+let pwaPath;
+beforeAll(() => {
+  global.fetch = realFetch;
+  pwaPath = fs.mkdtempSync(path.join(os.tmpdir(), 'proxy-test-pwa-'));
+  fs.writeFileSync(path.join(pwaPath, 'index.html'), '<html><body>test</body></html>');
+});
+
+function makeApp() {
+  return createProxyApp({ pwaPath, appVersion: '0.0.0-test' });
+}
+
+// Helper to make a request to the Express app without starting a persistent server
+async function request(app, method, url) {
+  return new Promise((resolve) => {
+    const server = app.listen(0, 'localhost', () => {
+      const port = server.address().port;
+      realFetch(`http://localhost:${port}${url}`, { method })
+        .then(async (res) => {
+          const body = await res.text();
+          server.close();
+          resolve({ status: res.status, body, headers: res.headers });
+        })
+        .catch((err) => {
+          server.close();
+          resolve({ status: 0, body: err.message, headers: new Headers() });
+        });
+    });
+  });
+}
+
+describe('createProxyApp', () => {
+  it('serves PWA at /player/pwa/', async () => {
+    const app = makeApp();
+    const res = await request(app, 'GET', '/player/pwa/');
+    expect(res.status).toBe(200);
+    expect(res.body).toContain('test');
+  });
+
+  it('redirects / to /player/pwa/', async () => {
+    const app = makeApp();
+    // fetch follows redirects by default, so we check the final body
+    const res = await request(app, 'GET', '/');
+    expect(res.status).toBe(200);
+    expect(res.body).toContain('test');
+  });
+
+  it('returns 400 for /xmds-proxy without cms param', async () => {
+    const app = makeApp();
+    const res = await request(app, 'GET', '/xmds-proxy');
+    expect(res.status).toBe(400);
+    expect(res.body).toContain('Missing cms parameter');
+  });
+
+  it('returns 400 for /rest-proxy without cms param', async () => {
+    const app = makeApp();
+    const res = await request(app, 'GET', '/rest-proxy');
+    expect(res.status).toBe(400);
+    expect(res.body).toContain('Missing cms parameter');
+  });
+
+  it('returns 400 for /file-proxy without cms param', async () => {
+    const app = makeApp();
+    const res = await request(app, 'GET', '/file-proxy');
+    expect(res.status).toBe(400);
+    expect(res.body).toContain('Missing cms or url parameter');
+  });
+
+  it('SPA fallback serves index.html for sub-routes', async () => {
+    const app = makeApp();
+    const res = await request(app, 'GET', '/player/pwa/some/deep/route');
+    expect(res.status).toBe(200);
+    expect(res.body).toContain('test');
+  });
+});

package/vitest.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals: true,
+  },
+});