Cloud Recording

starting ──tick/egress start──▶ running ──stop──▶ stopping ──▶ stopped
    │                               │
    └────────upstream failure───────┴──▶ failed

// acquire →
{ "resourceId": "res_9f2c…" }

// start →
{ "resourceId": "res_9f2c…", "sid": "rec_1a2b…", "serverResponse": { "taskId": "rec_1a2b…", "state": "starting" } }

// query →
{ "resourceId": "res_9f2c…", "sid": "rec_1a2b…",
  "serverResponse": { "taskId": "rec_1a2b…", "status": "running", "fileList": [{ "fileName": "recordings/rec_1a2b…/recording.mp4", "duration": 60, "size": 1048576 }] } }

import { seedChannel, tick, uniqueChannel } from './_lib.mjs';

export const meta = {
  id: '13-recordings-lifecycle',
  title: '云端录制：平台任务与声网 acquire→start 流程',
  safe: false, // 会创建任务并写入演示项目数据
  needsApi: true,
};

/**
 * 平台接口：POST /v1/recordings → GET /v1/recordings/{id} → POST /v1/recordings/{id}/layout → stop
 * 声网兼容：POST /v1/apps/{appid}/cloud_recording/acquire → .../mode/mix/start → query →
 *          updateLayout → stop
 *
 * 任务状态机：starting → running → stopping → stopped（失败为 failed，空闲超时为 expired）。
 * 真实的 Egress 由独立节点池执行；本地 memory adapter 下由调度器推进。
 */
export async function run(ctx) {
  const api = ctx.api;
  const appId = ctx.credentials.appId;
  const channelName = uniqueChannel('docs-rec');
  const uid = 92001;

  const seeded = await seedChannel(api, appId, channelName, uid);

  // ---------------------------------------------------------------- 平台接口
  const created = await api('POST', '/v1/recordings', {
    body: { channelName, mode: 'composite', layout: { preset: 'grid' }, idempotencyKey: `docs-${channelName}` },
  });
  ctx.assert(created.status === 202, `创建录制应返回 202，实际 ${created.status}`);
  const taskId = created.json.id;
  ctx.assert(created.json.state === 'starting', '新任务应为 starting');

  const duplicate = await api('POST', '/v1/recordings', {
    body: { channelName, mode: 'composite', idempotencyKey: `docs-${channelName}` },
  });
  ctx.assert(duplicate.json.id === taskId, '相同 idempotencyKey 应返回同一任务');

  await tick(api);
  const afterTick = await api('GET', `/v1/recordings/${taskId}`);
  const layoutUpdate = await api('POST', `/v1/recordings/${taskId}/layout`, { body: { preset: 'bestFit' } });
  ctx.assert(layoutUpdate.json.layout?.preset === 'bestFit', '布局应更新为 bestFit');

  const stopped = await api('POST', `/v1/recordings/${taskId}/stop`);
  ctx.assert(['stopping', 'stopped'].includes(stopped.json.state), `停止后应为 stopping/stopped，实际 ${stopped.json.state}`);

  // ------------------------------------------------------------- 声网兼容流程
  const acquire = await api('POST', `/v1/apps/${appId}/cloud_recording/acquire`, {
    body: { cname: channelName, uid: String(uid), clientRequest: { scene: 0 } },
  });
  const resourceId = acquire.json.resourceId;
  ctx.assert(typeof resourceId === 'string' && resourceId.startsWith('res_'), 'acquire 应返回 resourceId');

  const start = await api('POST', `/v1/apps/${appId}/cloud_recording/resourceid/${resourceId}/mode/mix/start`, {
    body: { cname: channelName, uid: String(uid), clientRequest: { recordingConfig: { mixedVideoLayout: 1 } } },
  });
  const sid = start.json.sid;
  ctx.assert(start.json.resourceId === resourceId, 'start 应回显 resourceId');
  ctx.assert(typeof sid === 'string' && sid.length > 0, 'start 应返回 sid');

  await tick(api);
  const query = await api('GET', `/v1/apps/${appId}/cloud_recording/resourceid/${resourceId}/sid/${sid}/mode/mix/query`);
  ctx.assert(query.json.serverResponse?.taskId === sid, 'query 应返回 taskId');
  ctx.assert(Array.isArray(query.json.serverResponse?.fileList), 'query 应返回 fileList');

  const agoraLayout = await api(
    'POST',
    `/v1/apps/${appId}/cloud_recording/resourceid/${resourceId}/sid/${sid}/mode/mix/updateLayout`,
    { body: { cname: channelName, uid: String(uid), clientRequest: { mixedVideoLayout: 2 } } },
  );
  ctx.assert(agoraLayout.json.serverResponse?.layout?.preset === 'pip', 'mixedVideoLayout=2 应映射为 pip');

  const agoraStop = await api(
    'POST',
    `/v1/apps/${appId}/cloud_recording/resourceid/${resourceId}/sid/${sid}/mode/mix/stop`,
    { body: { cname: channelName, uid: String(uid), clientRequest: {} } },
  );
  ctx.assert(
    ['stopping', 'stopped'].includes(agoraStop.json.serverResponse?.status),
    `声网 stop 状态应为 stopping/stopped，实际 ${agoraStop.json.serverResponse?.status}`,
  );

  // 复用已消费的 resourceId 必须失败（单次使用 + 30s TTL）
  const reused = await ctx.client('POST', `/v1/apps/${appId}/cloud_recording/resourceid/${resourceId}/mode/mix/start`, {
    body: { cname: channelName, uid: String(uid) },
  });
  ctx.assert(reused.status === 400, 'resourceId 不可复用，应返回 400');

  return {
    summary:
      `频道 ${channelName}：平台任务 ${taskId}（tick 后 ${afterTick.json.state} → ${stopped.json.state}）；` +
      `声网 sid=${sid}（query status=${query.json.serverResponse.status}）；重复 resourceId 正确拒绝`,
    details: {
      platformTask: { id: taskId, stateAfterTick: afterTick.json.state, layout: layoutUpdate.json.layout, finalState: stopped.json.state },
      agora: { resourceId, sid, query: query.json.serverResponse.status, layout: agoraLayout.json.serverResponse.layout },
      seededUid: seeded.uid,
    },
  };
}

#!/usr/bin/env bash
# 云端录制（声网兼容流程）：acquire → start → query → updateLayout → stop
# 注意：acquire 返回的 resourceId 单次使用、30 秒内有效；start 会消耗它。
set -euo pipefail

: "${NIMEET_API_BASE:=http://127.0.0.1:8787}"
: "${CNAME:=weekly-sync}"
: "${REC_UID:=10001}"
: "${MODE:=mix}"          # mix | individual | web
CRED_FILE=$([ -f the control plane class="tok-flag">-credentials.json ] && echo the control plane class="tok-flag">-credentials.json || echo data/demo-credentials.json)
CRED=$(node -e "const c=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'));process.stdout.write(Buffer.from(c.customerId+':'+c.customerSecret).toString('base64'))" "$CRED_FILE")
APP_ID=$(node -e "process.stdout.write(JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')).appId)" "$CRED_FILE")

BASE="$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording"

# 1) acquire：拿一次性 resourceId
ACQUIRE=$(curl -s -X POST "$BASE/acquire" \
  -H "Authorization: Basic $CRED" -H 'Content-Type: application/json' \
  -d "{\"cname\":\"$CNAME\",\"uid\":\"$REC_UID\",\"clientRequest\":{\"scene\":0}}")
RESOURCE_ID=$(node -e "process.stdout.write(JSON.parse(process.argv[1]).resourceId)" "$ACQUIRE")
echo "resourceId=$RESOURCE_ID"

# 2) start：mixedVideoLayout 0=grid 1=bestFit 2=pip 3=single
START=$(curl -s -X POST "$BASE/resourceid/$RESOURCE_ID/mode/$MODE/start" \
  -H "Authorization: Basic $CRED" -H 'Content-Type: application/json' \
  -d "{\"cname\":\"$CNAME\",\"uid\":\"$REC_UID\",\"clientRequest\":{\"recordingConfig\":{\"mixedVideoLayout\":1}}}")
SID=$(node -e "process.stdout.write(JSON.parse(process.argv[1]).sid)" "$START")
echo "sid=$SID"

# 3) query：状态 + 文件列表
curl -s "$BASE/resourceid/$RESOURCE_ID/sid/$SID/mode/$MODE/query" \
  -H "Authorization: Basic $CRED"

# 4) updateLayout：运行中改布局（仅 composite/mix 模式）
curl -s -X POST "$BASE/resourceid/$RESOURCE_ID/sid/$SID/mode/$MODE/updateLayout" \
  -H "Authorization: Basic $CRED" -H 'Content-Type: application/json' \
  -d "{\"cname\":\"$CNAME\",\"uid\":\"$REC_UID\",\"clientRequest\":{\"mixedVideoLayout\":2}}"

# 5) stop：返回最终 fileList
curl -s -X POST "$BASE/resourceid/$RESOURCE_ID/sid/$SID/mode/$MODE/stop" \
  -H "Authorization: Basic $CRED" -H 'Content-Type: application/json' \
  -d "{\"cname\":\"$CNAME\",\"uid\":\"$REC_UID\",\"clientRequest\":{}}"

{
  "noticeId": "ntc_…",
  "productId": 1,
  "eventType": 201,
  "notifyMs": 1793000000000,
  "sid": "prj_…:recording_state_changed",
  "payload": {
    "taskId": "rec_1a2b…",
    "channelName": "weekly-sync",
    "mode": "composite",
    "state": "stopped",
    "files": [{ "objectKey": "recordings/rec_1a2b…/recording.mp4", "durationSeconds": 60 }],
    "ts": 1793000000
  }
}