feat(phase2e-2): media-server Task 0/1/2 落地 + 代码审查修复

本次提交一次性落盘 Phase 2e-2 的 Task 0（PoC Spike）、Task 1（骨架 + Fastify 5 升级）
和 Task 2（9 个内部 REST API + code-reviewer 审查修复），覆盖 media-server 子项目
从零到可用的全部工作。

【Task 0 - PoC Spike】
- media-server/poc/：Node + mediasoup + fastify-websocket + 前端 mediasoup-client
- Playwright 双 tab 自动化验证 2 人会议：4 transports / 4 producers / 4 consumers / RSS 61MB
- media-server/docs/poc-notes.md 归档 7 项关键坑 + 启动步骤 + Task 1/2/9 复用映射
- 锁定技术栈：mediasoup + fastify + mediasoup-client，不改用 livekit-server

【Task 1 - 骨架 + Fastify 5 升级】
- 依赖版本：mediasoup@3.19.0 + fastify@5.8.5 + fastify-plugin@5.1.0
           + @fastify/sensible@6.0.4 + @fastify/websocket@11.2.0
           + pino@9.3.2 + zod@3.23.8
- src 五件套：app.ts / config.ts / utils/logger.ts / mediasoup/worker.ts
             / middlewares/internal-auth.ts
- /healthz + /readyz + /internal/info 三端点实测通过
- X-Internal-Token 鉴权用 timingSafeEqual 防侧信道
- mediasoup Worker died 指数退避自愈通过 kill -9 验证
- 多阶段 Dockerfile：非 root + curl HEALTHCHECK + 暴露 40000-40199 UDP/TCP
- Fastify 4 → 5 升级：loggerInstance: logger 消灭两个 pino 实例

【Task 2 - 9 个内部 REST API + 审查修复】
接口全部挂 /internal/v1/* 前缀，覆盖 Router/Transport/Producer/Consumer 完整生命周期：
- POST /routers, DELETE /routers/:id
- POST /transports, POST /transports/:id/connect
- POST /producers, DELETE /producers/:id
- POST /consumers, POST /consumers/:id/resume, DELETE /consumers/:id

工程特性：
- zod 手动 parse + 全局 errorHandler（不引入 fastify-type-provider-zod 避免
  zod v4 依赖冲突）
- AppError 统一错误码（NOT_FOUND/CONFLICT/CAN_NOT_CONSUME/ROUTER_LIMIT_EXCEEDED
  /MEDIASOUP_ERROR/VALIDATION_ERROR/UNAUTHORIZED/INTERNAL_ERROR）
- 所有资源用 Map + observer.once('close') 自清理，Consumer 监听 producerclose 级联关闭
- Consumer 强制 paused:true 创建，/resume 独立接口
- Transport direction 强约束：recv 拒 produce、send 拒 consume

code-reviewer 子代理审查"有条件通过"，同步修复：
- M1 _clearXxxMap 新增 src/utils/test-guard.ts#assertTestOnly 守卫（生产误调用抛错）
- M2 新增 src/schemas/rtp.ts 对 rtpParameters / rtpCapabilities 做 codecs 浅层校验
  （mimeType/clockRate/payloadType 必填、codecs ≥1），消除 as unknown as 双跳断言
- m1 connectTransport 改乐观锁：先置位再 await，失败回退
- m2 改读 consumer.producerPaused（更符合 mediasoup 语义）
- m3 producerclose 改为 once（风格一致）
- m5 internal-auth 改为反向白名单 PRIVATE_PATH_PREFIXES = ['/internal/']

验证：
- typecheck / lint 0 错误
- vitest：65 passed / 8 spec 文件
- 覆盖率 stmts 82.87% / branches 75.83% / funcs 91.3% / lines 82.87%
- 9 接口 happy path + 6 类错误路径 curl 手测全部按预期返回

【文档同步】
- CURRENT_STATUS.md +232 行：新增 Task 0/1/2 完整记录 + 代码审查修复章节 + 延后清单
- project-context.mdc：Task 0/1/2 状态同步
- phase2e-2-design.md +20 行：Fastify 5 升级相关决策记录
- phase2e-2-implementation.plan.md +117 行：Task 0/1/2 实际产出 + 修复记录

余下 Minor/Nits（m4/m6~m10/n1~n10）登记至 Task 16 收尾清单一次性清扫。

Made-with: Cursor

media-server/tests/app.spec.ts

@@ -0,0 +1,275 @@
+import type { FastifyInstance } from 'fastify';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { buildApp } from '../src/app.js';
+import { config } from '../src/config.js';
+import { closeWorker, startWorker } from '../src/mediasoup/worker.js';
+import { _clearConsumerMap } from '../src/services/consumer.service.js';
+import { _clearProducerMap } from '../src/services/producer.service.js';
+import { _clearRouterMap } from '../src/services/router.service.js';
+import { _clearTransportMap } from '../src/services/transport.service.js';
+
+let app: FastifyInstance;
+const token = config.internalToken;
+
+beforeAll(async () => {
+  app = (await buildApp()) as unknown as FastifyInstance;
+  await app.ready();
+  await startWorker();
+});
+
+afterAll(async () => {
+  _clearConsumerMap();
+  _clearProducerMap();
+  _clearTransportMap();
+  _clearRouterMap();
+  await app.close();
+  await closeWorker();
+});
+
+describe('HTTP layer: health + auth', () => {
+  it('GET /healthz returns ok snapshot', async () => {
+    const res = await app.inject({ method: 'GET', url: '/healthz' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.service).toBe('media-server');
+    expect(body.mediasoupVersion).toBeTruthy();
+  });
+
+  it('GET /readyz returns 200 when worker ready', async () => {
+    const res = await app.inject({ method: 'GET', url: '/readyz' });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().ready).toBe(true);
+  });
+
+  it('GET /internal/info without token returns 401', async () => {
+    const res = await app.inject({ method: 'GET', url: '/internal/info' });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('GET /internal/info with wrong token returns 401', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/internal/info',
+      headers: { 'x-internal-token': 'wrong-token-wrong-token' },
+    });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('GET /internal/info with valid token returns worker info', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/internal/info',
+      headers: { 'x-internal-token': token },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.service).toBe('media-server');
+    expect(body.mediasoupVersion).toBeTruthy();
+  });
+});
+
+describe('HTTP layer: /internal/v1/* routes', () => {
+  let routerId = '';
+  let sendTransportId = '';
+  let recvTransportId = '';
+
+  it('POST /internal/v1/routers 201', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/routers',
+      headers: { 'x-internal-token': token },
+      payload: { roomCode: 'ROOM-HTTP-1' },
+    });
+    expect(res.statusCode).toBe(201);
+    const body = res.json();
+    expect(body.routerId).toBeTruthy();
+    routerId = body.routerId;
+  });
+
+  it('POST /internal/v1/routers validation error returns 400', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/routers',
+      headers: { 'x-internal-token': token },
+      payload: { roomCode: 'lower-case' },
+    });
+    expect(res.statusCode).toBe(400);
+    const body = res.json();
+    expect(body.code).toBe('VALIDATION_ERROR');
+    expect(Array.isArray(body.fieldErrors)).toBe(true);
+  });
+
+  it('POST /internal/v1/transports (send) 201', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/transports',
+      headers: { 'x-internal-token': token },
+      payload: { routerId, userId: 'u-1', direction: 'send' },
+    });
+    expect(res.statusCode).toBe(201);
+    sendTransportId = res.json().id;
+    expect(sendTransportId).toBeTruthy();
+  });
+
+  it('POST /internal/v1/transports (recv) 201', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/transports',
+      headers: { 'x-internal-token': token },
+      payload: { routerId, userId: 'u-2', direction: 'recv' },
+    });
+    expect(res.statusCode).toBe(201);
+    recvTransportId = res.json().id;
+    expect(recvTransportId).toBeTruthy();
+  });
+
+  it('POST /internal/v1/transports with unknown router returns 404', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/transports',
+      headers: { 'x-internal-token': token },
+      payload: { routerId: 'bogus-router', userId: 'u-3', direction: 'send' },
+    });
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('NOT_FOUND');
+  });
+
+  const sampleAudioRtpParameters = {
+    codecs: [
+      { mimeType: 'audio/opus', clockRate: 48000, channels: 2, payloadType: 100 },
+    ],
+    encodings: [{ ssrc: 222222 }],
+  };
+
+  it('POST /internal/v1/producers with empty codecs returns 400 VALIDATION_ERROR', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/producers',
+      headers: { 'x-internal-token': token },
+      payload: {
+        transportId: recvTransportId,
+        kind: 'audio',
+        rtpParameters: { codecs: [] },
+      },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('VALIDATION_ERROR');
+  });
+
+  it('POST /internal/v1/producers with recv transport returns 409', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/producers',
+      headers: { 'x-internal-token': token },
+      payload: {
+        transportId: recvTransportId,
+        kind: 'audio',
+        rtpParameters: sampleAudioRtpParameters,
+      },
+    });
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('CONFLICT');
+  });
+
+  it('POST /internal/v1/consumers with empty codecs returns 400 VALIDATION_ERROR', async () => {
+    const producerRes = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/producers',
+      headers: { 'x-internal-token': token },
+      payload: {
+        transportId: sendTransportId,
+        kind: 'audio',
+        rtpParameters: sampleAudioRtpParameters,
+      },
+    });
+    expect(producerRes.statusCode).toBe(201);
+    const producerId = producerRes.json().id;
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/consumers',
+      headers: { 'x-internal-token': token },
+      payload: {
+        routerId,
+        transportId: recvTransportId,
+        producerId,
+        rtpCapabilities: { codecs: [] },
+      },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('VALIDATION_ERROR');
+  });
+
+  it('POST /internal/v1/consumers with incompatible codecs returns 400 CAN_NOT_CONSUME', async () => {
+    const producerRes = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/producers',
+      headers: { 'x-internal-token': token },
+      payload: {
+        transportId: sendTransportId,
+        kind: 'audio',
+        rtpParameters: {
+          ...sampleAudioRtpParameters,
+          encodings: [{ ssrc: 333333 }],
+        },
+      },
+    });
+    expect(producerRes.statusCode).toBe(201);
+    const producerId = producerRes.json().id;
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/consumers',
+      headers: { 'x-internal-token': token },
+      payload: {
+        routerId,
+        transportId: recvTransportId,
+        producerId,
+        rtpCapabilities: {
+          // 故意给一个 payloadType 不在 router 中的假 codec
+          codecs: [{ mimeType: 'audio/unknown-fake', clockRate: 48000 }],
+        },
+      },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('CAN_NOT_CONSUME');
+  });
+
+  it('DELETE /internal/v1/producers/:id returns 404 for unknown', async () => {
+    const res = await app.inject({
+      method: 'DELETE',
+      url: '/internal/v1/producers/unknown-id',
+      headers: { 'x-internal-token': token },
+    });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('POST /internal/v1/consumers/:id/resume returns 404 for unknown', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/internal/v1/consumers/unknown-id/resume',
+      headers: { 'x-internal-token': token },
+    });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('DELETE /internal/v1/consumers/:id returns 404 for unknown', async () => {
+    const res = await app.inject({
+      method: 'DELETE',
+      url: '/internal/v1/consumers/unknown-id',
+      headers: { 'x-internal-token': token },
+    });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('DELETE /internal/v1/routers/:routerId cleans up', async () => {
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/internal/v1/routers/${routerId}`,
+      headers: { 'x-internal-token': token },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().ok).toBe(true);
+  });
+});

media-server/tests/errors.spec.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+
+import { AppError, conflict, notFound } from '../src/utils/errors.js';
+
+describe('AppError', () => {
+  it('maps NOT_FOUND to 404', () => {
+    const err = notFound('router', 'r-1');
+    expect(err).toBeInstanceOf(AppError);
+    expect(err.code).toBe('NOT_FOUND');
+    expect(err.statusCode).toBe(404);
+    expect(err.message).toContain('r-1');
+    expect(err.toJSON()).toMatchObject({
+      code: 'NOT_FOUND',
+      message: expect.stringContaining('router'),
+      details: { resource: 'router', id: 'r-1' },
+    });
+  });
+
+  it('maps CONFLICT to 409', () => {
+    const err = conflict('already connected');
+    expect(err.statusCode).toBe(409);
+    expect(err.code).toBe('CONFLICT');
+  });
+
+  it('maps ROUTER_LIMIT_EXCEEDED to 503', () => {
+    const err = new AppError('ROUTER_LIMIT_EXCEEDED', 'too many routers');
+    expect(err.statusCode).toBe(503);
+  });
+
+  it('maps CAN_NOT_CONSUME to 400', () => {
+    const err = new AppError('CAN_NOT_CONSUME', 'nope');
+    expect(err.statusCode).toBe(400);
+  });
+
+  it('maps MEDIASOUP_ERROR to 500', () => {
+    const err = new AppError('MEDIASOUP_ERROR', 'boom');
+    expect(err.statusCode).toBe(500);
+  });
+
+  it('toJSON omits details when not provided', () => {
+    const err = new AppError('CONFLICT', 'just a conflict');
+    expect(err.toJSON()).toEqual({ code: 'CONFLICT', message: 'just a conflict' });
+  });
+});

media-server/tests/schemas.spec.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  idStringSchema,
+  roomCodeSchema,
+  userIdSchema,
+} from '../src/schemas/common.js';
+import { createConsumerBodySchema } from '../src/schemas/consumer.schema.js';
+import { createProducerBodySchema } from '../src/schemas/producer.schema.js';
+import { createRouterBodySchema } from '../src/schemas/router.schema.js';
+import {
+  connectTransportBodySchema,
+  createTransportBodySchema,
+} from '../src/schemas/transport.schema.js';
+
+describe('common schemas', () => {
+  it('accepts valid id strings', () => {
+    expect(idStringSchema.parse('abc-123_X:Y')).toBe('abc-123_X:Y');
+  });
+
+  it('rejects invalid characters in id', () => {
+    expect(() => idStringSchema.parse('abc/def')).toThrow();
+    expect(() => idStringSchema.parse('')).toThrow();
+    expect(() => idStringSchema.parse('a'.repeat(200))).toThrow();
+  });
+
+  it('accepts valid room codes', () => {
+    expect(roomCodeSchema.parse('ROOM-001')).toBe('ROOM-001');
+  });
+
+  it('rejects lowercase or invalid room codes', () => {
+    expect(() => roomCodeSchema.parse('room-001')).toThrow();
+    expect(() => roomCodeSchema.parse('AB')).toThrow();
+  });
+
+  it('coerces numeric userIds into strings', () => {
+    expect(userIdSchema.parse(42)).toBe('42');
+    expect(userIdSchema.parse('alice')).toBe('alice');
+  });
+
+  it('rejects non-positive numeric userIds', () => {
+    expect(() => userIdSchema.parse(0)).toThrow();
+    expect(() => userIdSchema.parse(-1)).toThrow();
+  });
+});
+
+describe('router schema', () => {
+  it('parses valid body', () => {
+    expect(createRouterBodySchema.parse({ roomCode: 'ROOM-1' })).toEqual({
+      roomCode: 'ROOM-1',
+    });
+  });
+
+  it('rejects missing roomCode', () => {
+    expect(() => createRouterBodySchema.parse({})).toThrow();
+  });
+});
+
+describe('transport schemas', () => {
+  it('parses create body', () => {
+    const parsed = createTransportBodySchema.parse({
+      routerId: 'router-1',
+      userId: 'user-1',
+      direction: 'send',
+    });
+    expect(parsed.direction).toBe('send');
+  });
+
+  it('rejects bad direction', () => {
+    expect(() =>
+      createTransportBodySchema.parse({
+        routerId: 'router-1',
+        userId: 'user-1',
+        direction: 'bidirectional',
+      }),
+    ).toThrow();
+  });
+
+  it('parses connect body with fingerprints', () => {
+    const parsed = connectTransportBodySchema.parse({
+      dtlsParameters: {
+        role: 'auto',
+        fingerprints: [{ algorithm: 'sha-256', value: 'AA:BB' }],
+      },
+    });
+    expect(parsed.dtlsParameters.fingerprints).toHaveLength(1);
+  });
+
+  it('rejects connect body without fingerprints', () => {
+    expect(() =>
+      connectTransportBodySchema.parse({
+        dtlsParameters: { role: 'auto', fingerprints: [] },
+      }),
+    ).toThrow();
+  });
+});
+
+describe('producer schema', () => {
+  const validRtpParameters = {
+    codecs: [
+      { mimeType: 'audio/opus', clockRate: 48000, payloadType: 100, channels: 2 },
+    ],
+  };
+
+  it('parses valid body', () => {
+    const parsed = createProducerBodySchema.parse({
+      transportId: 'trans-1',
+      kind: 'audio',
+      rtpParameters: validRtpParameters,
+    });
+    expect(parsed.kind).toBe('audio');
+    expect(parsed.rtpParameters.codecs[0]?.payloadType).toBe(100);
+  });
+
+  it('rejects bad kind', () => {
+    expect(() =>
+      createProducerBodySchema.parse({
+        transportId: 'trans-1',
+        kind: 'data',
+        rtpParameters: validRtpParameters,
+      }),
+    ).toThrow();
+  });
+
+  it('rejects rtpParameters without codecs', () => {
+    expect(() =>
+      createProducerBodySchema.parse({
+        transportId: 'trans-1',
+        kind: 'audio',
+        rtpParameters: {},
+      }),
+    ).toThrow();
+  });
+
+  it('rejects rtpParameters with empty codecs', () => {
+    expect(() =>
+      createProducerBodySchema.parse({
+        transportId: 'trans-1',
+        kind: 'audio',
+        rtpParameters: { codecs: [] },
+      }),
+    ).toThrow();
+  });
+});
+
+describe('consumer schema', () => {
+  const validRtpCapabilities = {
+    codecs: [{ mimeType: 'audio/opus', clockRate: 48000 }],
+  };
+
+  it('parses valid body', () => {
+    const parsed = createConsumerBodySchema.parse({
+      routerId: 'r-1',
+      transportId: 't-1',
+      producerId: 'p-1',
+      rtpCapabilities: validRtpCapabilities,
+    });
+    expect(parsed.routerId).toBe('r-1');
+  });
+
+  it('rejects missing fields', () => {
+    expect(() =>
+      createConsumerBodySchema.parse({ routerId: 'r-1' }),
+    ).toThrow();
+  });
+
+  it('rejects rtpCapabilities with empty codecs', () => {
+    expect(() =>
+      createConsumerBodySchema.parse({
+        routerId: 'r-1',
+        transportId: 't-1',
+        producerId: 'p-1',
+        rtpCapabilities: { codecs: [] },
+      }),
+    ).toThrow();
+  });
+});

media-server/tests/services/consumer.service.spec.ts

@@ -0,0 +1,87 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { closeWorker, startWorker } from '../../src/mediasoup/worker.js';
+import {
+  closeConsumer,
+  createConsumer,
+  resumeConsumer,
+  _clearConsumerMap,
+} from '../../src/services/consumer.service.js';
+import { _clearProducerMap } from '../../src/services/producer.service.js';
+import { _clearRouterMap, createRouter } from '../../src/services/router.service.js';
+import {
+  _clearTransportMap,
+  createWebRtcTransport,
+} from '../../src/services/transport.service.js';
+import { AppError } from '../../src/utils/errors.js';
+
+let routerId = '';
+let sendTransportId = '';
+let recvTransportId = '';
+
+beforeAll(async () => {
+  await startWorker();
+  const r = await createRouter('ROOM-CONSUMER');
+  routerId = r.routerId;
+  sendTransportId = (
+    await createWebRtcTransport({ routerId, userId: 'u-s', direction: 'send' })
+  ).id;
+  recvTransportId = (
+    await createWebRtcTransport({ routerId, userId: 'u-r', direction: 'recv' })
+  ).id;
+});
+
+afterAll(async () => {
+  _clearConsumerMap();
+  _clearProducerMap();
+  _clearTransportMap();
+  _clearRouterMap();
+  await closeWorker();
+});
+
+describe('consumer.service', () => {
+  it('createConsumer with unknown router throws NOT_FOUND', async () => {
+    await expect(
+      createConsumer({
+        routerId: 'bogus-router',
+        transportId: recvTransportId,
+        producerId: 'bogus-producer',
+        rtpCapabilities: {} as never,
+      }),
+    ).rejects.toMatchObject({ code: 'NOT_FOUND' });
+  });
+
+  it('createConsumer with unknown producer throws NOT_FOUND', async () => {
+    await expect(
+      createConsumer({
+        routerId,
+        transportId: recvTransportId,
+        producerId: 'bogus-producer',
+        rtpCapabilities: {} as never,
+      }),
+    ).rejects.toMatchObject({ code: 'NOT_FOUND' });
+  });
+
+  it('createConsumer with unknown transport throws NOT_FOUND', async () => {
+    await expect(
+      createConsumer({
+        routerId,
+        transportId: 'bogus-transport',
+        producerId: 'bogus-producer',
+        rtpCapabilities: {} as never,
+      }),
+    ).rejects.toMatchObject({ code: 'NOT_FOUND' });
+  });
+
+  it('resumeConsumer throws NOT_FOUND for unknown id', async () => {
+    await expect(resumeConsumer('non-existent')).rejects.toMatchObject({ code: 'NOT_FOUND' });
+  });
+
+  it('closeConsumer throws NOT_FOUND for unknown id', async () => {
+    await expect(closeConsumer('non-existent')).rejects.toMatchObject({ code: 'NOT_FOUND' });
+  });
+
+  it('placeholder: send transport exists for coverage', () => {
+    expect(sendTransportId).toBeTruthy();
+  });
+});

media-server/tests/services/producer.service.spec.ts

@@ -0,0 +1,82 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+
+import { closeWorker, startWorker } from '../../src/mediasoup/worker.js';
+import {
+  closeProducer,
+  createProducer,
+  getProducer,
+  _clearProducerMap,
+} from '../../src/services/producer.service.js';
+import { _clearRouterMap, createRouter } from '../../src/services/router.service.js';
+import {
+  _clearTransportMap,
+  createWebRtcTransport,
+} from '../../src/services/transport.service.js';
+import { AppError } from '../../src/utils/errors.js';
+
+let recvTransportId = '';
+
+beforeAll(async () => {
+  await startWorker();
+  const { routerId } = await createRouter('ROOM-PRODUCER');
+  const recv = await createWebRtcTransport({
+    routerId,
+    userId: 'user-recv',
+    direction: 'recv',
+  });
+  recvTransportId = recv.id;
+});
+
+afterAll(async () => {
+  _clearProducerMap();
+  _clearTransportMap();
+  _clearRouterMap();
+  await closeWorker();
+});
+
+afterEach(() => {
+  _clearProducerMap();
+});
+
+describe('producer.service', () => {
+  it('getProducer throws NOT_FOUND for unknown id', () => {
+    try {
+      getProducer('non-existent');
+      throw new Error('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(AppError);
+      expect((err as AppError).code).toBe('NOT_FOUND');
+    }
+  });
+
+  it('closeProducer throws NOT_FOUND for unknown id', async () => {
+    await expect(closeProducer('non-existent')).rejects.toMatchObject({ code: 'NOT_FOUND' });
+  });
+
+  const validRtpParameters = {
+    codecs: [
+      { mimeType: 'audio/opus', clockRate: 48000, channels: 2, payloadType: 100 },
+    ],
+    encodings: [{ ssrc: 111111 }],
+  } as never;
+
+  it('createProducer rejects when transport direction is recv', async () => {
+    await expect(
+      createProducer({
+        transportId: recvTransportId,
+        kind: 'audio',
+        rtpParameters: validRtpParameters,
+      }),
+    ).rejects.toMatchObject({ code: 'CONFLICT' });
+  });
+
+  it('createProducer with unknown transport throws NOT_FOUND', async () => {
+    await expect(
+      createProducer({
+        transportId: 'bogus-transport',
+        kind: 'audio',
+        rtpParameters: validRtpParameters,
+      }),
+    ).rejects.toMatchObject({ code: 'NOT_FOUND' });
+  });
+});

media-server/tests/services/router.service.spec.ts

@@ -0,0 +1,81 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+
+import { config } from '../../src/config.js';
+import { closeWorker, startWorker } from '../../src/mediasoup/worker.js';
+import {
+  _clearRouterMap,
+  closeRouter,
+  createRouter,
+  getRouter,
+  getRouterStats,
+  tryGetRouter,
+} from '../../src/services/router.service.js';
+import { AppError } from '../../src/utils/errors.js';
+
+beforeAll(async () => {
+  await startWorker();
+});
+
+afterAll(async () => {
+  _clearRouterMap();
+  await closeWorker();
+});
+
+afterEach(() => {
+  _clearRouterMap();
+});
+
+describe('router.service', () => {
+  it('creates a router and returns rtpCapabilities', async () => {
+    const { routerId, rtpCapabilities } = await createRouter('ROOM-TEST-1');
+    expect(routerId).toBeTruthy();
+    expect(Array.isArray(rtpCapabilities.codecs)).toBe(true);
+    expect(rtpCapabilities.codecs?.length).toBeGreaterThan(0);
+
+    const stats = getRouterStats();
+    expect(stats.total).toBe(1);
+    expect(stats.rooms[0]?.roomCode).toBe('ROOM-TEST-1');
+  });
+
+  it('getRouter throws NOT_FOUND for unknown id', () => {
+    try {
+      getRouter('non-existent-id');
+      throw new Error('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(AppError);
+      expect((err as AppError).code).toBe('NOT_FOUND');
+    }
+  });
+
+  it('tryGetRouter returns undefined instead of throwing', () => {
+    expect(tryGetRouter('non-existent-id')).toBeUndefined();
+  });
+
+  it('closeRouter removes entry via observer close event', async () => {
+    const { routerId } = await createRouter('ROOM-TEST-2');
+    expect(getRouterStats().total).toBe(1);
+
+    await closeRouter(routerId);
+    // observer.once('close') executes synchronously when router.close() is called
+    expect(getRouterStats().total).toBe(0);
+  });
+
+  it('closeRouter throws NOT_FOUND for unknown router', async () => {
+    await expect(closeRouter('non-existent-id')).rejects.toBeInstanceOf(AppError);
+  });
+
+  it('enforces router limit', async () => {
+    const originalLimit = config.mediasoup.maxRouters;
+    (config.mediasoup as { maxRouters: number }).maxRouters = 2;
+
+    try {
+      await createRouter('ROOM-LIMIT-1');
+      await createRouter('ROOM-LIMIT-2');
+      await expect(createRouter('ROOM-LIMIT-3')).rejects.toMatchObject({
+        code: 'ROUTER_LIMIT_EXCEEDED',
+      });
+    } finally {
+      (config.mediasoup as { maxRouters: number }).maxRouters = originalLimit;
+    }
+  });
+});

media-server/tests/services/transport.service.spec.ts

@@ -0,0 +1,75 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+
+import { closeWorker, startWorker } from '../../src/mediasoup/worker.js';
+import { _clearRouterMap, createRouter } from '../../src/services/router.service.js';
+import {
+  _clearTransportMap,
+  createWebRtcTransport,
+  getTransport,
+  getTransportStats,
+} from '../../src/services/transport.service.js';
+import { AppError } from '../../src/utils/errors.js';
+
+let routerId = '';
+
+beforeAll(async () => {
+  await startWorker();
+  const r = await createRouter('ROOM-TRANSPORT');
+  routerId = r.routerId;
+});
+
+afterAll(async () => {
+  _clearTransportMap();
+  _clearRouterMap();
+  await closeWorker();
+});
+
+afterEach(() => {
+  _clearTransportMap();
+});
+
+describe('transport.service', () => {
+  it('creates a WebRTC transport and returns ICE/DTLS params', async () => {
+    const transport = await createWebRtcTransport({
+      routerId,
+      userId: 'user-1',
+      direction: 'send',
+    });
+    expect(transport.id).toBeTruthy();
+    expect(transport.iceParameters.usernameFragment).toBeTruthy();
+    expect(transport.iceParameters.password).toBeTruthy();
+    expect(Array.isArray(transport.iceCandidates)).toBe(true);
+    expect(transport.iceCandidates.length).toBeGreaterThan(0);
+    expect(transport.dtlsParameters.fingerprints.length).toBeGreaterThan(0);
+    expect(getTransportStats().total).toBe(1);
+  });
+
+  it('supports recv direction', async () => {
+    const transport = await createWebRtcTransport({
+      routerId,
+      userId: 'user-2',
+      direction: 'recv',
+    });
+    expect(transport.id).toBeTruthy();
+  });
+
+  it('getTransport throws NOT_FOUND for unknown id', () => {
+    try {
+      getTransport('non-existent');
+      throw new Error('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(AppError);
+      expect((err as AppError).code).toBe('NOT_FOUND');
+    }
+  });
+
+  it('createWebRtcTransport with unknown routerId throws NOT_FOUND', async () => {
+    await expect(
+      createWebRtcTransport({
+        routerId: 'bogus-router',
+        userId: 'user-3',
+        direction: 'send',
+      }),
+    ).rejects.toMatchObject({ code: 'NOT_FOUND' });
+  });
+});

media-server/tests/setup.ts

@@ -0,0 +1,7 @@
+process.env.NODE_ENV = 'test';
+process.env.MEDIA_INTERNAL_TOKEN = process.env.MEDIA_INTERNAL_TOKEN ?? 'test-token-1234567890';
+process.env.LOG_LEVEL = process.env.LOG_LEVEL ?? 'silent';
+process.env.LOG_PRETTY = process.env.LOG_PRETTY ?? 'false';
+process.env.MEDIASOUP_RTC_MIN_PORT = process.env.MEDIASOUP_RTC_MIN_PORT ?? '40800';
+process.env.MEDIASOUP_RTC_MAX_PORT = process.env.MEDIASOUP_RTC_MAX_PORT ?? '40899';
+process.env.MEDIASOUP_WORKER_LOG_LEVEL = process.env.MEDIASOUP_WORKER_LOG_LEVEL ?? 'error';

media-server/tests/test-guard.spec.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+
+import { assertTestOnly } from '../src/utils/test-guard.js';
+
+describe('assertTestOnly', () => {
+  it('passes when NODE_ENV=test', () => {
+    expect(() => assertTestOnly('sampleFn')).not.toThrow();
+  });
+
+  it('throws when NODE_ENV is not test', () => {
+    const original = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+    try {
+      expect(() => assertTestOnly('sampleFn')).toThrow(/test-only/);
+    } finally {
+      process.env.NODE_ENV = original;
+    }
+  });
+});