@modesto_ma/dsh-channels 0.6.0 → 0.8.0-beta.1

package/src/analyze/server.ts

@@ -1,207 +0,0 @@
-/**
- * The analyze API's HTTP route on the DSH Web server.
- *
- * Registers the exact route `POST /api/dsh-channels.logalyze` (see
- * `./contract.ts`) on the host `webServer`; hosts without one (headless) have
- * no analyze API. This module owns the transport-level checks, in order:
- * path, the `analyzeEnabled` switch, method, bearer token, `Idempotency-Key`,
- * media type, body size, and JSON validation; everything after validation
- * belongs to the {@link AnalyzeHandler}. Bodies, tokens, and prompts are never
- * logged.
- *
- * @module dsh-channels/analyze/server
- */
-
-import { createHash, timingSafeEqual } from 'node:crypto'
-import type { IncomingMessage, ServerResponse } from 'node:http'
-import type { HostContext } from '../dsh-types.ts'
-import {
-  ANALYZE_MAX_BODY_BYTES, ANALYZE_ROUTE, IDEMPOTENCY_KEY_PATTERN, parseAnalyzeRequest,
-} from './contract.ts'
-import type { AnalyzeRequest, AnalyzeResponse } from './contract.ts'
-
-/** The narrow `ctx.webServer` surface the analyze route registers into. */
-export interface HostWebServer {
-  register(route: {
-    kind: 'exact'
-    path: string
-    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
-  }): () => void
-}
-
-/** The business side of the route. */
-export interface AnalyzeHandler {
-  /**
-   * Whether the API is switched on (`analyzeEnabled`), read per request.
-   * @returns false to answer every request with 404.
-   */
-  enabled(): boolean
-  /**
-   * Resolve the expected bearer token for this request.
-   * @returns the token, or undefined when it is not configured.
-   */
-  token(): Promise<string | undefined>
-  /**
-   * Accept one validated request.
-   * @param request - the validated body.
-   * @param idempotencyKey - the request's `Idempotency-Key`.
-   * @returns the HTTP answer.
-   */
-  analyze(request: AnalyzeRequest, idempotencyKey: string): Promise<AnalyzeResponse>
-}
-
-class HttpError extends Error {
-  constructor(readonly status: number, message: string) {
-    super(message)
-  }
-}
-
-function send(res: ServerResponse, response: AnalyzeResponse): void {
-  const body = JSON.stringify(response.body)
-  res.writeHead(response.status, {
-    'content-type': 'application/json; charset=utf-8',
-    'cache-control': 'no-store',
-    'content-length': Buffer.byteLength(body),
-  })
-  res.end(body)
-}
-
-function refuse(res: ServerResponse, status: number, error: string, headers: Record<string, string> = {}): void {
-  for (const [name, value] of Object.entries(headers)) res.setHeader(name, value)
-  send(res, { status, body: { ok: false, error } })
-}
-
-/** Constant-time token comparison over fixed-length digests. */
-function tokenMatches(presented: string, expected: string): boolean {
-  const left = createHash('sha256').update(presented).digest()
-  const right = createHash('sha256').update(expected).digest()
-  return timingSafeEqual(left, right)
-}
-
-/** The bearer credential of one request, or undefined. */
-function bearerOf(req: IncomingMessage): string | undefined {
-  const header = req.headers.authorization
-  if (header === undefined) return undefined
-  const match = /^Bearer[ \t]+(\S+)[ \t]*$/iu.exec(header)
-  return match?.[1]
-}
-
-/** Read the body up to {@link ANALYZE_MAX_BODY_BYTES}; larger bodies fail with 413. */
-async function readBody(req: IncomingMessage): Promise<string> {
-  const declared = Number(req.headers['content-length'])
-  if (Number.isFinite(declared) && declared > ANALYZE_MAX_BODY_BYTES) {
-    throw new HttpError(413, `请求体超过 ${ANALYZE_MAX_BODY_BYTES} 字节`)
-  }
-  const chunks: Buffer[] = []
-  let size = 0
-  for await (const chunk of req) {
-    const buffer = chunk as Buffer
-    size += buffer.length
-    if (size > ANALYZE_MAX_BODY_BYTES) throw new HttpError(413, `请求体超过 ${ANALYZE_MAX_BODY_BYTES} 字节`)
-    chunks.push(buffer)
-  }
-  return Buffer.concat(chunks).toString('utf8')
-}
-
-/**
- * Handle one HTTP request against the analyze contract.
- * @param req - the incoming request.
- * @param res - its response.
- * @param handler - the business side.
- */
-export async function handleAnalyzeHttp(
-  req: IncomingMessage,
-  res: ServerResponse,
-  handler: AnalyzeHandler,
-): Promise<void> {
-  const pathname = new URL(req.url ?? '/', 'http://analyze.invalid').pathname
-  if (pathname !== ANALYZE_ROUTE) {
-    refuse(res, 404, '未知路径')
-    return
-  }
-  if (!handler.enabled()) {
-    refuse(res, 404, '日志分析接口未开启，请在设置面板「高级 → 日志分析接口」打开开关')
-    return
-  }
-  if ((req.method ?? 'GET').toUpperCase() !== 'POST') {
-    refuse(res, 405, '只接受 POST', { allow: 'POST' })
-    return
-  }
-  const expected = await handler.token()
-  if (expected === undefined || expected === '') {
-    refuse(res, 503, '分析接口未配置访问令牌，请联系部署者配置 analyzeToken 引用的凭据')
-    return
-  }
-  const presented = bearerOf(req)
-  if (presented === undefined || !tokenMatches(presented, expected)) {
-    refuse(res, 401, '访问令牌无效', { 'www-authenticate': 'Bearer' })
-    return
-  }
-  const idempotencyKey = req.headers['idempotency-key']
-  if (typeof idempotencyKey !== 'string' || !IDEMPOTENCY_KEY_PATTERN.test(idempotencyKey)) {
-    refuse(res, 400, '缺少或不合法的 Idempotency-Key 请求头（1-200 个可见 ASCII 字符）')
-    return
-  }
-  const mediaType = (req.headers['content-type'] ?? '').split(';')[0]?.trim().toLowerCase()
-  if (mediaType !== 'application/json') {
-    refuse(res, 415, 'Content-Type 必须是 application/json')
-    return
-  }
-  let raw: unknown
-  try {
-    raw = JSON.parse(await readBody(req))
-  } catch (error) {
-    if (error instanceof HttpError) {
-      refuse(res, error.status, error.message)
-      return
-    }
-    refuse(res, 400, '请求体不是合法的 JSON')
-    return
-  }
-  const parsed = parseAnalyzeRequest(raw)
-  if (!parsed.ok) {
-    refuse(res, 400, parsed.error)
-    return
-  }
-  send(res, await handler.analyze(parsed.value, idempotencyKey))
-}
-
-/**
- * Register the analyze route on the host Web server once it is available.
- * Requests skip the DSH login gate on purpose: the bearer token is this API's
- * only credential.
- * @param ctx - the plugin context.
- * @param handler - the business side.
- * @param warn - diagnostics sink for unexpected handler failures.
- */
-export function mountAnalyzeRoute(
-  ctx: HostContext,
-  handler: AnalyzeHandler,
-  warn: (message: string, ...args: unknown[]) => void,
-): void {
-  const attach = (webCtx: HostContext): void => {
-    const server = webCtx.get?.('webServer') as HostWebServer | undefined
-    if (server === undefined) return
-    webCtx.effect(() => server.register({
-      kind: 'exact',
-      path: ANALYZE_ROUTE,
-      handler: async (req, res) => {
-        try {
-          await handleAnalyzeHttp(req, res, handler)
-        } catch (error) {
-          warn('dsh-channels: analyze request failed: %s', String(error))
-          if (!res.headersSent) refuse(res, 500, `分析请求处理失败：${String(error)}`)
-          else res.destroy()
-        }
-      },
-    }), 'dsh-channels: analyze route')
-  }
-  const inject = (ctx as {
-    inject?: (dependencies: string[], callback: (child: HostContext) => void) => unknown
-  }).inject
-  if (typeof inject === 'function') {
-    inject.call(ctx, ['webServer'], attach)
-    return
-  }
-  attach(ctx)
-}

package/src/cards/analyze.ts

@@ -1,116 +0,0 @@
-/**
- * Root card of a log-platform analysis: who started which analysis when, the
- * log-platform detail pages behind it, and a status tag (分析中 → 已完成 /
- * 已停止 / 失败 / 已中断). The analysis itself streams in the topic below the
- * card through the ordinary streaming card.
- *
- * @module dsh-channels/cards/analyze
- */
-
-import { CARD_CONFIG, CARD_SCHEMA, markdown, note } from './primitives.ts'
-
-/** One log-platform detail page listed on the root card. */
-export interface AnalyzeLogDetail {
-  readonly name: string
-  readonly url: string
-}
-
-/** Subject of one analysis, as the root card names it. */
-export interface AnalyzeSubject {
-  /** Requester user_id (rendered as an @-mention). */
-  readonly requesterUserId: string
-  /** Trigger time as the platform sent it (shown verbatim). */
-  readonly triggeredAt: string
-  readonly app: string
-  readonly errorCode: string
-  readonly logDetails: readonly AnalyzeLogDetail[]
-}
-
-/**
- * Root card status: `running` until the first turn settles (`done`,
- * `stopped`, `error`), `failed` when the analysis could not start, or
- * `interrupted` when DSH restarted before the first turn settled.
- */
-export type AnalyzeStatus =
-  | { readonly kind: 'running' }
-  | { readonly kind: 'done' }
-  | { readonly kind: 'stopped' }
-  | { readonly kind: 'error' }
-  | { readonly kind: 'failed'; readonly reason: string }
-  | { readonly kind: 'interrupted' }
-
-/** Rows per table page (Feishu caps `page_size` at 10). */
-const TABLE_PAGE_SIZE = 10
-
-/** Escape markdown emphasis characters in platform-supplied text. */
-function plain(text: string): string {
-  return text.replace(/([*_~`[\]\\])/gu, '\\$1')
-}
-
-/** Percent-encode the characters that would end a markdown link target early. */
-function linkTarget(url: string): string {
-  return url.replace(/[()\s]/gu, char => `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`)
-}
-
-/** Header tag text, tag color, and header template of each status. */
-function statusLook(status: AnalyzeStatus): { tag: string; color: string; template: string } {
-  switch (status.kind) {
-    case 'running': return { tag: '分析中', color: 'blue', template: 'blue' }
-    case 'done': return { tag: '已完成', color: 'green', template: 'green' }
-    case 'stopped': return { tag: '已停止', color: 'neutral', template: 'grey' }
-    case 'error':
-    case 'failed': return { tag: '失败', color: 'red', template: 'red' }
-    case 'interrupted': return { tag: '已中断', color: 'orange', template: 'orange' }
-  }
-}
-
-/** Footer line of each status. */
-function statusNote(status: AnalyzeStatus): string {
-  switch (status.kind) {
-    case 'running': return '分析过程在本卡片下的话题内实时输出；群内已授权的成员可以在话题内直接回复追问。'
-    case 'done': return '分析已完成，结果见话题；在话题内回复即可继续追问。'
-    case 'stopped': return '分析已停止；在话题内回复即可继续。'
-    case 'error': return '分析回合失败，原因见话题；在话题内回复即可重试或追问。'
-    case 'failed': return `分析未能开始：${plain(status.reason)}`
-    case 'interrupted': return 'DSH 重启导致分析中断；在话题内回复即可继续。'
-  }
-}
-
-/**
- * The analysis root card.
- * @param subject - the analysis subject.
- * @param status - the status the card shows.
- * @returns card JSON.
- */
-export function buildAnalyzeRootCard(subject: AnalyzeSubject, status: AnalyzeStatus): object {
-  const look = statusLook(status)
-  return {
-    schema: CARD_SCHEMA,
-    config: CARD_CONFIG,
-    header: {
-      title: { tag: 'plain_text', content: '日志分析' },
-      template: look.template,
-      text_tag_list: [{ tag: 'text_tag', text: { tag: 'plain_text', content: look.tag }, color: look.color }],
-    },
-    body: {
-      elements: [
-        markdown(`<at id=${subject.requesterUserId}></at> 于 ${plain(subject.triggeredAt)} 发起了对 **${plain(subject.app)}** 应用 **${plain(subject.errorCode)}** 错误码不良日志的分析。`),
-        {
-          tag: 'table',
-          page_size: TABLE_PAGE_SIZE,
-          row_height: 'low',
-          header_style: { background_style: 'grey', bold: true, lines: 1 },
-          columns: [
-            { name: 'name', display_name: '日志', data_type: 'text', width: 'auto' },
-            { name: 'link', display_name: '详情页', data_type: 'markdown', width: 'auto' },
-          ],
-          rows: subject.logDetails.map(detail => ({
-            name: detail.name,
-            link: `[查看](${linkTarget(detail.url)})`,
-          })),
-        },
-        note(statusNote(status)),
-      ],
-    },
-  }
-}