@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/event.js

@@ -0,0 +1,151 @@
+// 变更事件与订阅：`event --list|--subscriptions|--subscribe|--replay`（契约 §2）。
+//
+// 读事件比读业务数据更敏感（事件流等于全量变更面）：服务端用 `admin:audit` 门禁，
+// 所以普通业务员跑 `event --list` 会拿到 403 `authz.missing_scope`（退出码 4）——
+// 这是对的，不是 bug。
+//
+// 两条与 Rust 逐条对齐、容易"顺手改错"的地方：
+//
+// 1. `--list` / `--subscriptions` 是纯读，Rust **没有**给它们 `--dry-run` 分支，
+//    Node 版照抄（`--dry-run` 在这两条上仍会真的发请求）；
+// 2. `--subscribe` / `--replay` 是写，但 Rust **没有**给它们生成幂等键
+//    （服务端这两条路由也不要求 `Idempotency-Key`：建订阅/重放不是"重放即等值"的
+//    幂等写）。这里保持与 Rust **同一份线上请求**：不加键。
+//    文件/附件域的写操作则一律带键（见 `file.js`）。
+
+import { CliError, exactlyOne } from '../core/error.js';
+import { flagList, flagOn, flagValue, intFlag } from '../core/args.js';
+import { requestSpec } from '../core/http.js';
+import { dataOf } from '../core/runtime.js';
+import { resolveTenant } from './file.js';
+
+/**
+ * `event` 的动作分发。
+ *
+ * 与 Rust 的 clap `ArgGroup(action, multiple=false)` 同义：四个动作**恰好一个**。
+ * 规格驱动的解析器不替我们做这件事（`--list` 这类动作旗标只在 `extra_flags` 里），
+ * `event --list --replay sub_1` 这种命令行必须在这里拒掉（Rust 退出码 2、不发请求）。
+ */
+export async function handleEvent({ args, runtime }) {
+  const picked = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--subscribe', flagOn(args, '--subscribe')],
+      ['--subscriptions', flagOn(args, '--subscriptions')],
+      ['--replay', args['--replay'] !== undefined],
+    ],
+    'event',
+    '例：xinhe-oa-cli event --list --since-seq 0 --limit 20 --json',
+  );
+  if (picked === '--list') return list(runtime, args);
+  if (picked === '--subscriptions') return subscriptions(runtime);
+  if (picked === '--subscribe') return subscribe(runtime, args);
+  return replay(runtime, args);
+}
+
+/** `event --list [--since-seq N] [--limit N] [--resource-type T]... [--operation OP]`。 */
+async function list(runtime, args) {
+  // `--since-seq` 是 i64（可以是 0 或正数游标），`--limit` 是 u32。
+  const query = [
+    ['since_seq', String(intFlag(args, '--since-seq', { fallback: 0 }))],
+    ['limit', String(intFlag(args, '--limit', { fallback: 100, min: 0 }))],
+  ];
+  for (const resourceType of flagList(args, '--resource-type')) {
+    query.push(['resource_types', resourceType]);
+  }
+  const resourceId = flagValue(args, '--resource-id');
+  if (resourceId !== null) query.push(['resource_id', resourceId]);
+  const operation = flagList(args, '--operation')[0];
+  if (operation !== undefined) query.push(['operation', operation]);
+
+  const response = await runtime.sendAuthed('GET', '/events', requestSpec({ query }));
+  const body = dataOf(response);
+  runtime.finishFrom(response, {
+    events: fieldOr(body, 'events', []),
+    since_seq: body?.since_seq ?? null,
+    next_seq: body?.next_seq ?? null,
+    has_more: body?.has_more ?? null,
+    next_step: '接着读：把这个 next_seq 传回 --since-seq 继续（游标补偿）',
+  });
+}
+
+/** `event --subscriptions`：列出订阅（含游标与投递统计）。 */
+async function subscriptions(runtime) {
+  const response = await runtime.sendAuthed('GET', '/event-subscriptions', requestSpec());
+  const body = dataOf(response);
+  runtime.finishFrom(response, {
+    subscriptions: fieldOr(body, 'subscriptions', []),
+    total: body?.total ?? null,
+  });
+}
+
+/** `event --subscribe --tenant <T> --name <名字> --target-url <http(s)://...>`。 */
+async function subscribe(runtime, args) {
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '建订阅');
+  const name = flagValue(args, '--name');
+  if (name === null) throw CliError.usage('`event --subscribe` 需要 --name <订阅名>');
+  const targetUrl = flagValue(args, '--target-url');
+  if (targetUrl === null) {
+    throw CliError.usage('`event --subscribe` 需要 --target-url <http(s)://...>').withHint(
+      '服务端只接受 http:// 或 https:// 开头（其它 scheme 是 SSRF 面）',
+    );
+  }
+  // scheme 白名单在**本地**判：非 http(s) 的目标地址是 SSRF 面，客户端完全能提前拦下。
+  if (!(targetUrl.startsWith('http://') || targetUrl.startsWith('https://'))) {
+    throw CliError.usage('--target-url 必须是 http:// 或 https:// 开头').withHint(
+      '例：--target-url https://example.com/hooks/oa',
+    );
+  }
+  const spec = requestSpec({
+    body: {
+      tenant,
+      name,
+      target_url: targetUrl,
+      resource_types: flagList(args, '--resource-type'),
+      operations: flagList(args, '--operation'),
+    },
+  });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', '/event-subscriptions', spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('POST', '/event-subscriptions', spec);
+  runtime.finishFrom(response, { subscription: dataOf(response) });
+}
+
+/** `event --replay <SUBSCRIPTION_ID> [--since-seq N]`（高风险：必须 `--yes`）。 */
+async function replay(runtime, args) {
+  const subscriptionId = String(args['--replay'] ?? '');
+  runtime.requireYes(
+    'event --replay（把死信重新投递到客户的外部地址）',
+    `xinhe-oa-cli event --replay ${subscriptionId}`,
+  );
+  const spec = requestSpec({
+    body: { since_seq: intFlag(args, '--since-seq', { fallback: 0 }) },
+  });
+  const requestPath = `/event-subscriptions/${subscriptionId}/replay`;
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('POST', requestPath, spec);
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    // 服务端回 `{replayed: N}`；形状不对时把整个 `data` 交出去（不静默丢字段）。
+    replayed: fieldOr(data, 'replayed', data),
+    subscription_id: subscriptionId,
+  });
+}
+
+/**
+ * 取字段：**键存在就用它的值**（哪怕是 `null`），键不存在才用兜底。
+ *
+ * 与 Rust 的 `body.get(key).cloned().unwrap_or(fallback)` 同义 ——
+ * 用 JS 的 `??` 会把"服务端明确回了 null"和"服务端没回这个键"混成一种。
+ */
+function fieldOr(body, key, fallback) {
+  if (body !== null && typeof body === 'object' && !Array.isArray(body) && key in body) {
+    return body[key];
+  }
+  return fallback;
+}