dsh-plugin-container 0.0.0-stage → 0.3.0

package/src/host/attach.js

@@ -0,0 +1,246 @@
+/**
+ * Interactive PTY sessions for `docker attach` and Apple `container exec`.
+ *
+ * The DSH subprocess service exposes spawnTerminal, whose handle owns a PTY,
+ * raw output stream, write(), resize(), and terminate(). This manager keeps the
+ * PTY process out of the one-shot JobManager: attach sessions are long-lived,
+ * browser-driven, and have their own bounded output buffer.
+ */
+import { randomUUID } from 'node:crypto'
+
+import { codeOf, messageOf } from './util.js'
+
+const MAX_SESSIONS = 2
+const MAX_INPUT_BYTES = 8192
+const MAX_COLS = 300
+const MIN_COLS = 20
+const MAX_ROWS = 120
+const MIN_ROWS = 5
+
+/** @param {unknown} value @param {number} min @param {number} max @param {number} fallback */
+function dimension(value, min, max, fallback) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.min(Math.max(Math.trunc(number), min), max)
+}
+
+/** @param {unknown} value @param {string} message @param {string} code */
+function attachError(message, code) {
+  return Object.assign(new Error(message), { code })
+}
+
+export class AttachManager {
+  /**
+   * @param {{
+   *   subprocess: any,
+   *   maxBytes?: number,
+   *   maxSessions?: number,
+   * }} options
+   */
+  constructor(options) {
+    this.subprocess = options.subprocess
+    this.maxBytes = Math.min(Math.max(Number(options.maxBytes ?? 1_500_000), 64 * 1024), 8 * 1024 * 1024)
+    this.maxSessions = Math.min(Math.max(Number(options.maxSessions ?? MAX_SESSIONS), 1), 8)
+    this.sessions = new Map()
+  }
+
+  /**
+   * @param {{
+   *   argv: string[],
+   *   cwd: string,
+   *   env?: NodeJS.ProcessEnv,
+   *   provider: string,
+   *   containerId: string,
+   *   containerName?: string,
+   *   command: string,
+   *   mode?: 'attach' | 'exec',
+   *   cols?: number,
+   *   rows?: number,
+   *   signal?: AbortSignal,
+   * }} input
+   */
+  async start(input) {
+    if (typeof this.subprocess.spawnTerminal !== 'function') {
+      throw attachError('当前 DSH 版本不支持 PTY 终端，无法 attach', 'docker/attach-unsupported')
+    }
+    if (this.sessions.size >= this.maxSessions) {
+      throw attachError(`最多同时打开 ${String(this.maxSessions)} 个 attach 终端，请先关闭一个`, 'docker/attach-limit')
+    }
+    const cols = dimension(input.cols, MIN_COLS, MAX_COLS, 120)
+    const rows = dimension(input.rows, MIN_ROWS, MAX_ROWS, 30)
+    let handle
+    try {
+      handle = await this.subprocess.spawnTerminal({
+        argv: input.argv,
+        cwd: input.cwd,
+        cols,
+        rows,
+        terminalType: 'xterm-256color',
+        env: input.env ?? {},
+        graceMs: 2000,
+        signal: input.signal,
+      })
+    } catch (error) {
+      throw attachError(`无法启动 attach 终端: ${messageOf(error)}`, 'docker/attach-failed')
+    }
+    if (handle === null || typeof handle !== 'object' || handle.output === undefined || typeof handle.write !== 'function') {
+      try { await handle?.terminate?.() } catch { /* best effort */ }
+      throw attachError('attach 终端句柄不可用', 'docker/attach-failed')
+    }
+
+    const id = `attach_${randomUUID()}`
+    /** @type {any} */
+    const session = {
+      id,
+      provider: input.provider,
+      containerId: input.containerId,
+      containerName: input.containerName ?? input.containerId,
+      command: input.command,
+      mode: input.mode === 'exec' ? 'exec' : 'attach',
+      cols,
+      rows,
+      status: 'running',
+      exitCode: null,
+      startedAt: Date.now(),
+      endedAt: null,
+      error: null,
+      output: '',
+      /** Absolute offset of output[0] within the session's full output. */
+      baseOffset: 0,
+      handle,
+      closed: false,
+    }
+    this.sessions.set(id, session)
+    handle.output.on('data', (chunk) => this.append(session, String(chunk)))
+    handle.done.then(
+      (outcome) => {
+        if (session.closed) return
+        session.status = 'exited'
+        session.exitCode = outcome?.exitCode ?? null
+        session.endedAt = Date.now()
+      },
+      (error) => {
+        if (session.closed) return
+        session.status = 'failed'
+        session.endedAt = Date.now()
+        session.error = messageOf(error)
+      },
+    )
+    return this.info(session)
+  }
+
+  /** @param {any} session @param {string} text */
+  append(session, text) {
+    if (text === '') return
+    session.output += text
+    if (session.output.length > this.maxBytes) {
+      const remove = session.output.length - this.maxBytes
+      session.output = session.output.slice(remove)
+      session.baseOffset += remove
+    }
+  }
+
+  /** @param {any} session */
+  info(session) {
+    return {
+      id: session.id,
+      provider: session.provider,
+      containerId: session.containerId,
+      containerName: session.containerName,
+      command: session.command,
+      mode: session.mode,
+      cols: session.cols,
+      rows: session.rows,
+      status: session.status,
+      exitCode: session.exitCode,
+      startedAt: session.startedAt,
+      endedAt: session.endedAt,
+      error: session.error,
+    }
+  }
+
+  /** @param {string} id */
+  require(id) {
+    if (typeof id !== 'string' || id === '') throw attachError('缺少 attachId', 'docker/attach-unknown')
+    const session = this.sessions.get(id)
+    if (session === undefined) throw attachError('attach 会话不存在或已关闭', 'docker/attach-unknown')
+    return session
+  }
+
+  /** @param {Record<string, any>} input */
+  poll(input) {
+    const session = this.require(input.attachId)
+    const requested = Number(input.offset)
+    const offset = Number.isFinite(requested) && requested >= 0 ? Math.trunc(requested) : 0
+    const lossy = offset < session.baseOffset
+    const start = Math.max(offset, session.baseOffset) - session.baseOffset
+    return {
+      session: this.info(session),
+      output: {
+        text: session.output.slice(start),
+        nextOffset: session.baseOffset + session.output.length,
+        lossy,
+      },
+    }
+  }
+
+  /** @param {Record<string, any>} input */
+  async write(input) {
+    const session = this.require(input.attachId)
+    if (session.status !== 'running') throw attachError('attach 终端已结束', 'docker/attach-closed')
+    const data = input.data
+    if (typeof data !== 'string' || data === '') throw attachError('缺少输入内容', 'docker/attach-input')
+    if (Buffer.byteLength(data, 'utf8') > MAX_INPUT_BYTES) throw attachError('单次输入过长', 'docker/attach-input')
+    try {
+      await session.handle.write(data)
+    } catch (error) {
+      throw attachError(`写入 attach 终端失败: ${messageOf(error)}`, 'docker/attach-input')
+    }
+    return this.info(session)
+  }
+
+  /** @param {Record<string, any>} input */
+  async resize(input) {
+    const session = this.require(input.attachId)
+    if (session.status !== 'running') return this.info(session)
+    const cols = dimension(input.cols, MIN_COLS, MAX_COLS, session.cols)
+    const rows = dimension(input.rows, MIN_ROWS, MAX_ROWS, session.rows)
+    try {
+      await session.handle.resize(cols, rows)
+      session.cols = cols
+      session.rows = rows
+    } catch (error) {
+      throw attachError(`调整 attach 终端大小失败: ${messageOf(error)}`, 'docker/attach-resize')
+    }
+    return this.info(session)
+  }
+
+  /** @param {Record<string, any>} input */
+  async close(input) {
+    const session = this.require(input.attachId)
+    session.closed = true
+    session.status = 'closed'
+    session.endedAt = Date.now()
+    try {
+      await session.handle.terminate()
+    } catch (error) {
+      if (codeOf(error) !== 'ESRCH') session.error = messageOf(error)
+    } finally {
+      this.sessions.delete(session.id)
+    }
+    return this.info(session)
+  }
+
+  async dispose() {
+    const sessions = [...this.sessions.values()]
+    this.sessions.clear()
+    await Promise.allSettled(sessions.map(async (session) => {
+      session.closed = true
+      await session.handle.terminate()
+    }))
+  }
+}
+
+export function createAttachManager(options) {
+  return new AttachManager(options)
+}

package/src/host/commands.js

@@ -0,0 +1,235 @@
+/**
+ * Docker command parsing and safety policy.
+ *
+ * Commands are never handed to a shell. The tokenizer only splits argv, and
+ * shell operators are rejected so a pasted `docker ps | grep x` fails loudly
+ * instead of silently becoming arguments to Docker.
+ */
+import { basename, isAbsolute } from 'node:path'
+
+import {
+  MAX_ARG_BYTES,
+  MAX_ARGV,
+  MAX_COMMAND_BYTES,
+  displayCommand,
+  messageOf,
+  requireString,
+} from './util.js'
+
+const SHELL_OPERATORS = new Set(['|', '&', ';', '<', '>', '(', ')', '`', '$'])
+const FORBIDDEN_GLOBAL_FLAGS = new Set(['--context', '--host', '--config'])
+const FORBIDDEN_GLOBAL_PREFIXES = ['--tls', '-H']
+const DESTRUCTIVE_FIRST = new Set(['rm', 'rmi', 'prune', 'kill', 'stop', 'delete'])
+const DESTRUCTIVE_GROUPS = new Set(['volume', 'network', 'container', 'image', 'builder'])
+const SENSITIVE_MARKERS = new Set(['login', 'logout', '--password', '--password-stdin', '--token', '--registry-token'])
+
+export class CommandError extends Error {
+  /** @param {string} message @param {string} [code] */
+  constructor(message, code = 'docker/invalid-command') {
+    super(message)
+    this.name = 'CommandError'
+    this.code = code
+  }
+}
+
+/** @param {string} input */
+function tokenize(input) {
+  if (Buffer.byteLength(input, 'utf8') > MAX_COMMAND_BYTES) throw new CommandError('命令太长（上限 8 KiB）')
+  if (input.includes('\0')) throw new CommandError('命令包含非法 NUL 字符')
+
+  const tokens = []
+  let current = ''
+  let quote = null
+  let hasToken = false
+  let index = 0
+
+  const push = () => {
+    if (!hasToken) return
+    tokens.push(current)
+    current = ''
+    hasToken = false
+    if (tokens.length > MAX_ARGV) throw new CommandError(`参数过多（上限 ${MAX_ARGV} 项）`)
+  }
+
+  while (index < input.length) {
+    const char = input[index]
+    if (quote === "'") {
+      if (char === "'") quote = null
+      else current += char
+      hasToken = true
+      index += 1
+      continue
+    }
+    if (quote === '"') {
+      if (char === '"') {
+        quote = null
+        index += 1
+        continue
+      }
+      if (char === '\\') {
+        const next = input[index + 1]
+        if (next === undefined) throw new CommandError('命令以未完成的转义结尾')
+        current += next
+        hasToken = true
+        index += 2
+        continue
+      }
+      current += char
+      hasToken = true
+      index += 1
+      continue
+    }
+    if (char === "'" || char === '"') {
+      quote = char
+      hasToken = true
+      index += 1
+      continue
+    }
+    if (char === '\\') {
+      const next = input[index + 1]
+      if (next === undefined) throw new CommandError('命令以未完成的转义结尾')
+      current += next
+      hasToken = true
+      index += 2
+      continue
+    }
+    if (SHELL_OPERATORS.has(char)) {
+      throw new CommandError('不支持管道、重定向、命令替换等 shell 语法；请分开执行，或改用快捷操作')
+    }
+    if (/\s/u.test(char)) {
+      push()
+      index += 1
+      continue
+    }
+    current += char
+    hasToken = true
+    index += 1
+  }
+  if (quote !== null) throw new CommandError('引号没有闭合')
+  push()
+  for (const token of tokens) {
+    if (Buffer.byteLength(token, 'utf8') > MAX_ARG_BYTES) throw new CommandError('单个参数太长（上限 4 KiB）')
+  }
+  return tokens
+}
+
+/**
+ * Parse free-form command text into a Docker subcommand argv.
+ * @param {string} input
+ * @param {{dockerPath?: string}} [options]
+ */
+export function parseCommand(input, options = {}) {
+  const text = requireString(input, 'command', { max: MAX_COMMAND_BYTES, allowEmpty: true })
+  const tokens = tokenize(text.trim())
+  return normalizeSubcommand(tokens, options)
+}
+
+/**
+ * Parse shell-free argument text without stripping a leading command name.
+ * Used by structured actions such as `run <image> <args>`.
+ * @param {string} input
+ * @returns {string[]}
+ */
+export function parseArguments(input) {
+  const text = requireString(input, 'arguments', { max: MAX_COMMAND_BYTES, allowEmpty: true })
+  return tokenize(text.trim())
+}
+
+/**
+ * Normalize both free-form and structured input to the argv after `docker`.
+ * @param {unknown} value
+ * @param {{dockerPath?: string}} [options]
+ */
+export function normalizeSubcommand(value, options = {}) {
+  const commandName = options.commandName ?? 'docker'
+  if (!Array.isArray(value)) throw new CommandError('argv 必须是字符串数组')
+  if (value.length === 0) throw new CommandError(`请输入 ${commandName} 命令`)
+  if (value.length > MAX_ARGV) throw new CommandError(`参数过多（上限 ${MAX_ARGV} 项）`)
+  const tokens = value.map((token, index) => requireString(token, `argv[${index}]`))
+  let argv = tokens
+  const binaryName = options.dockerPath ? basename(options.dockerPath) : commandName
+  if (argv[0] === commandName || argv[0] === binaryName || argv[0] === options.dockerPath) argv = argv.slice(1)
+  if (argv.length === 0) throw new CommandError(`请输入 ${commandName} 子命令`)
+  if (argv[0] === 'sudo' || argv[0] === 'env') throw new CommandError(`只能执行 ${commandName} 子命令，不能执行其他程序`)
+  if (commandName === 'container' && argv[0] === 'docker') throw new CommandError('当前 provider 是 Apple container，请使用 container 命令')
+  for (const token of argv) {
+    if (FORBIDDEN_GLOBAL_FLAGS.has(token) || token.startsWith('--context=') || token.startsWith('--host=') || token.startsWith('--config=')) {
+      throw new CommandError(`不允许在命令中覆盖 ${token}；请使用面板的上下文选择器`)
+    }
+    if (FORBIDDEN_GLOBAL_PREFIXES.some((prefix) => token === prefix || token.startsWith(`${prefix}=`) || (prefix === '-H' && token.startsWith('-H') && token.length > 2))) {
+      throw new CommandError(`不允许在命令中覆盖 ${token}；连接目标由上下文决定`)
+    }
+  }
+  return argv
+}
+
+/**
+ * @param {string | undefined | null} context
+ * @param {{known?: Set<string>}} [options]
+ * @returns {string | null}
+ */
+export function normalizeContext(context, options = {}) {
+  if (context === undefined || context === null || context === '') return null
+  if (typeof context !== 'string') throw new CommandError('context 必须是字符串')
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.@-]{0,127}$/u.test(context)) throw new CommandError('context 名称不合法')
+  if (options.known !== undefined && !options.known.has(context)) throw new CommandError(`未知的 Docker context: ${context}`, 'docker/context-unknown')
+  return context
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {{dangerous: boolean, reason: string | null}}
+ */
+export function detectDestructive(argv) {
+  const first = argv[0]
+  const second = argv[1]
+  if (DESTRUCTIVE_FIRST.has(first)) {
+    if (first === 'stop' || first === 'kill') return { dangerous: true, reason: 'stop' }
+    if (first === 'rm' || first === 'rmi' || first === 'delete') return { dangerous: true, reason: 'delete' }
+    return { dangerous: true, reason: 'prune' }
+  }
+  if (first === 'compose' && (second === 'down' || second === 'rm')) return { dangerous: true, reason: 'compose-down' }
+  if (first === 'system' && second === 'prune') return { dangerous: true, reason: 'prune' }
+  if (DESTRUCTIVE_GROUPS.has(first) && (second === 'rm' || second === 'delete' || second === 'prune')) {
+    return { dangerous: true, reason: second === 'prune' ? 'prune' : 'delete' }
+  }
+  if (first === 'swarm' && second === 'leave') return { dangerous: true, reason: 'delete' }
+  return { dangerous: false, reason: null }
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {boolean}
+ */
+export function isSensitiveCommand(argv) {
+  return argv.some((token) => SENSITIVE_MARKERS.has(token) || token.startsWith('--password=') || token.startsWith('--token='))
+}
+
+/**
+ * Resolve a client-provided cwd to an absolute existing directory.
+ * @param {unknown} value
+ * @param {{fallback: string, statSync: (path: string) => {isDirectory: () => boolean}}} options
+ */
+export function resolveCwd(value, options) {
+  if (value === undefined || value === null || value === '') return options.fallback
+  if (typeof value !== 'string') throw new CommandError('cwd 必须是字符串', 'docker/invalid-cwd')
+  if (!isAbsolute(value)) throw new CommandError('cwd 必须是绝对路径', 'docker/invalid-cwd')
+  if (value.includes('\0') || value.length > 4096) throw new CommandError('cwd 不合法', 'docker/invalid-cwd')
+  let stat
+  try {
+    stat = options.statSync(value)
+  } catch (error) {
+    throw new CommandError(`cwd 不存在或不可访问: ${messageOf(error)}`, 'docker/invalid-cwd')
+  }
+  if (!stat.isDirectory()) throw new CommandError('cwd 不是目录', 'docker/invalid-cwd')
+  return value
+}
+
+/**
+ * Build the client-facing display form without resolving the binary path.
+ * @param {string[]} argv
+ * @param {string | null} context
+ */
+export function describeCommand(argv, context, commandName = 'docker') {
+  return displayCommand(argv, context, commandName)
+}