feat: plugins v1

server/src/routes/index.ts

@@ -6,6 +6,8 @@ import gamesRouter from './games';
 import proxyRouter from './proxy';
 import usersRouter from './users';
 import serversRouter from './servers';
+import pluginSupportRouter from './plugin-support';
+import openApiDocsRouter from './openapi-docs';
 import joinRequestsRouter from './join-requests';
 import { invitesApiRouter, invitePageRouter } from './invites';
 
@@ -16,6 +18,8 @@ export function registerRoutes(app: Express): void {
   app.use('/api/games', gamesRouter);
   app.use('/api', proxyRouter);
   app.use('/api/users', usersRouter);
+  app.use('/api', openApiDocsRouter);
+  app.use('/api/servers', pluginSupportRouter);
   app.use('/api/servers', serversRouter);
   app.use('/api/invites', invitesApiRouter);
   app.use('/api/requests', joinRequestsRouter);

server/src/routes/openapi-docs.ts

@@ -0,0 +1,106 @@
+import { Router } from 'express';
+import { areOpenApiDocsEnabled, setOpenApiDocsEnabled } from '../config/variables';
+
+const router = Router();
+
+function createOpenApiDocument(baseUrl: string) {
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: 'MetoYou Plugin Support API',
+      version: '1.0.0',
+      description: 'Official HTTP endpoints for plugin metadata, event definitions, and plugin data. '
+        + 'Plugin code is never executed by the signal server.'
+    },
+    servers: [{ url: `${baseUrl}/api` }],
+    paths: {
+      '/servers/{serverId}/plugins': {
+        get: {
+          summary: 'Read plugin requirement snapshot',
+          parameters: [{ name: 'serverId', in: 'path', required: true, schema: { type: 'string' } }],
+          responses: { '200': { description: 'Plugin requirements and event definitions' } }
+        }
+      },
+      '/servers/{serverId}/plugins/{pluginId}/requirement': {
+        put: {
+          summary: 'Create or update a server plugin requirement',
+          responses: { '200': { description: 'Requirement saved' }, '403': { description: 'Not authorized' } }
+        },
+        delete: {
+          summary: 'Delete a server plugin requirement',
+          responses: { '200': { description: 'Requirement deleted' }, '403': { description: 'Not authorized' } }
+        }
+      },
+      '/servers/{serverId}/plugins/{pluginId}/events/{eventName}': {
+        put: {
+          summary: 'Create or update a plugin event definition',
+          responses: { '200': { description: 'Event definition saved' }, '403': { description: 'Not authorized' } }
+        },
+        delete: {
+          summary: 'Delete a plugin event definition',
+          responses: { '200': { description: 'Event definition deleted' }, '403': { description: 'Not authorized' } }
+        }
+      },
+      '/servers/{serverId}/plugins/{pluginId}/data': {
+        get: {
+          summary: 'List plugin data records',
+          responses: { '200': { description: 'Plugin data records' }, '403': { description: 'Not a server member' } }
+        }
+      },
+      '/servers/{serverId}/plugins/{pluginId}/data/{key}': {
+        put: {
+          summary: 'Write plugin data',
+          responses: { '200': { description: 'Plugin data saved' }, '403': { description: 'Not a server member' } }
+        },
+        delete: {
+          summary: 'Delete plugin data',
+          responses: { '200': { description: 'Plugin data deleted' }, '403': { description: 'Not a server member' } }
+        }
+      },
+      '/openapi/settings': {
+        get: { summary: 'Read OpenAPI docs setting', responses: { '200': { description: 'Setting value' } } },
+        put: { summary: 'Toggle OpenAPI docs exposure', responses: { '200': { description: 'Setting value' } } }
+      }
+    }
+  };
+}
+
+function docsDisabledResponse() {
+  return { error: 'OpenAPI docs are disabled', errorCode: 'OPENAPI_DOCS_DISABLED' };
+}
+
+router.get('/openapi/settings', (_req, res) => {
+  res.json({ enabled: areOpenApiDocsEnabled() });
+});
+
+router.put('/openapi/settings', (req, res) => {
+  res.json(setOpenApiDocsEnabled(req.body?.enabled === true));
+});
+
+router.get('/openapi.json', (req, res) => {
+  if (!areOpenApiDocsEnabled()) {
+    res.status(404).json(docsDisabledResponse());
+    return;
+  }
+
+  res.json(createOpenApiDocument(`${req.protocol}://${req.get('host') ?? 'localhost'}`));
+});
+
+router.get('/docs', (_req, res) => {
+  if (!areOpenApiDocsEnabled()) {
+    res.status(404).json(docsDisabledResponse());
+    return;
+  }
+
+  res.type('html').send(`<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>MetoYou Plugin API Docs</title></head>
+<body style="font-family:system-ui;margin:2rem;line-height:1.5">
+<h1>MetoYou Plugin Support API</h1>
+<p>Plugin support endpoints are available at <a href="/api/openapi.json">/api/openapi.json</a>.</p>
+<p>The signal server stores metadata, data, and event definitions only. It never executes plugin code.</p>
+</body>
+</html>`);
+});
+
+export default router;

server/src/routes/plugin-support.ts

@@ -0,0 +1,208 @@
+import { Response, Router } from 'express';
+import {
+  deletePluginData,
+  deletePluginEventDefinition,
+  deletePluginRequirement,
+  getPluginRequirementsSnapshot,
+  listPluginData,
+  PluginSupportError,
+  upsertPluginData,
+  upsertPluginEventDefinition,
+  upsertPluginRequirement
+} from '../services/plugin-support.service';
+import { broadcastToServer } from '../websocket/broadcast';
+
+const router = Router();
+
+function sendPluginSupportError(error: unknown, res: Response): void {
+  if (error instanceof PluginSupportError) {
+    res.status(error.status).json({ error: error.message, errorCode: error.code });
+    return;
+  }
+
+  console.error('Unhandled plugin support error:', error);
+  res.status(500).json({ error: 'Internal server error', errorCode: 'INTERNAL_ERROR' });
+}
+
+function readActorUserId(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+async function broadcastRequirementsSnapshot(serverId: string): Promise<void> {
+  const snapshot = await getPluginRequirementsSnapshot(serverId);
+
+  broadcastToServer(serverId, {
+    type: 'plugin_requirements_changed',
+    serverId,
+    snapshot
+  });
+}
+
+router.get('/:serverId/plugins', async (req, res) => {
+  try {
+    res.json(await getPluginRequirementsSnapshot(req.params.serverId));
+  } catch (error) {
+    sendPluginSupportError(error, res);
+  }
+});
+
+router.put('/:serverId/plugins/:pluginId/requirement', async (req, res) => {
+  const { serverId, pluginId } = req.params;
+
+  try {
+    const requirement = await upsertPluginRequirement({
+      actorUserId: readActorUserId(req.body.actorUserId),
+      pluginId,
+      reason: req.body.reason,
+      serverId,
+      status: req.body.status,
+      versionRange: req.body.versionRange
+    });
+
+    await broadcastRequirementsSnapshot(serverId);
+    res.json({ requirement });
+  } catch (error) {
+    sendPluginSupportError(error, res);
+  }
+});
+
+router.delete('/:serverId/plugins/:pluginId/requirement', async (req, res) => {
+  const { serverId, pluginId } = req.params;
+
+  try {
+    await deletePluginRequirement({
+      actorUserId: readActorUserId(req.body.actorUserId),
+      pluginId,
+      serverId
+    });
+
+    await broadcastRequirementsSnapshot(serverId);
+    res.json({ ok: true });
+  } catch (error) {
+    sendPluginSupportError(error, res);
+  }
+});
+
+router.put('/:serverId/plugins/:pluginId/events/:eventName', async (req, res) => {
+  const { serverId, pluginId, eventName } = req.params;
+
+  try {
+    const eventDefinition = await upsertPluginEventDefinition({
+      actorUserId: readActorUserId(req.body.actorUserId),
+      direction: req.body.direction,
+      eventName,
+      maxPayloadBytes: req.body.maxPayloadBytes,
+      pluginId,
+      rateLimitJson: req.body.rateLimitJson,
+      schemaJson: req.body.schemaJson,
+      scope: req.body.scope,
+      serverId
+    });
+
+    await broadcastRequirementsSnapshot(serverId);
+    res.json({ eventDefinition });
+  } catch (error) {
+    sendPluginSupportError(error, res);
+  }
+});
+
+router.delete('/:serverId/plugins/:pluginId/events/:eventName', async (req, res) => {
+  const { serverId, pluginId, eventName } = req.params;
+
+  try {
+    await deletePluginEventDefinition({
+      actorUserId: readActorUserId(req.body.actorUserId),
+      eventName,
+      pluginId,
+      serverId
+    });
+
+    await broadcastRequirementsSnapshot(serverId);
+    res.json({ ok: true });
+  } catch (error) {
+    sendPluginSupportError(error, res);
+  }
+});
+
+router.get('/:serverId/plugins/:pluginId/data', async (req, res) => {
+  const { serverId, pluginId } = req.params;
+
+  try {
+    const records = await listPluginData({
+      actorUserId: readActorUserId(req.query.userId),
+      key: req.query.key,
+      ownerId: req.query.ownerId,
+      pluginId,
+      scope: req.query.scope,
+      serverId
+    });
+
+    res.json({ records });
+  } catch (error) {
+    sendPluginSupportError(error, res);
+  }
+});
+
+router.put('/:serverId/plugins/:pluginId/data/:key', async (req, res) => {
+  const { serverId, pluginId, key } = req.params;
+
+  try {
+    const record = await upsertPluginData({
+      actorUserId: readActorUserId(req.body.actorUserId),
+      key,
+      ownerId: req.body.ownerId,
+      pluginId,
+      schemaVersion: req.body.schemaVersion,
+      scope: req.body.scope,
+      serverId,
+      value: req.body.value
+    });
+
+    broadcastToServer(serverId, {
+      type: 'plugin_data_changed',
+      serverId,
+      pluginId: record.pluginId,
+      scope: record.scope,
+      ownerId: record.ownerId,
+      key: record.key,
+      updatedAt: record.updatedAt
+    });
+
+    res.json({ record });
+  } catch (error) {
+    sendPluginSupportError(error, res);
+  }
+});
+
+router.delete('/:serverId/plugins/:pluginId/data/:key', async (req, res) => {
+  const { serverId, pluginId, key } = req.params;
+  const scope = req.body.scope ?? req.query.scope;
+  const ownerId = req.body.ownerId ?? req.query.ownerId;
+
+  try {
+    await deletePluginData({
+      actorUserId: readActorUserId(req.body.actorUserId),
+      key,
+      ownerId,
+      pluginId,
+      scope,
+      serverId
+    });
+
+    broadcastToServer(serverId, {
+      type: 'plugin_data_changed',
+      serverId,
+      pluginId,
+      scope: typeof scope === 'string' ? scope : 'server',
+      ownerId: typeof ownerId === 'string' && ownerId.trim() ? ownerId.trim() : undefined,
+      key,
+      updatedAt: Date.now()
+    });
+
+    res.json({ ok: true });
+  } catch (error) {
+    sendPluginSupportError(error, res);
+  }
+});
+
+export default router;