@dr-co/dsh-node-client 0.0.0-stage → 0.0.60

package/lib/jobs.mjs

@@ -0,0 +1,203 @@
+/**
+ * Долгоиграющие процессы: запустил, получил id, читаешь вывод по смещению.
+ *
+ * Отдельно от `exec`, потому что контракт другой: `exec` отвечает результатом,
+ * а здесь ответ — идентификатор, и дальше идут `output`, `kill`, `list`.
+ * Смешивать это в одном методе пришлось бы аргументами вроде `background`,
+ * половина которых бессмысленна в другом режиме.
+ *
+ * Модель повторяет поведение jobs в DSH: статус (`running`/`stopping`/
+ * `completed`/`killed`/`failed`), кольцевой буфер вывода и убийство всей
+ * группы процессов, а не одного pid.
+ *
+ * @module dsh-node-client/jobs
+ */
+import { spawn } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+
+import { commandArgv, killTree, spawnCommand, platform } from './shell.mjs'
+
+/** Сколько байт вывода держим на job: старое вытесняется. */
+const RING_BYTES = 256 * 1024
+/** Потолок одновременных job: иначе узел завалит сам себя. */
+const MAX_JOBS = 8
+/** Сколько завершённых помним: по ним смотрят, что было, но не бесконечно. */
+const MAX_FINISHED = 32
+
+/**
+ * Реестр фоновых процессов клиента.
+ * @param {object} [options]
+ * @param {number} [options.ringBytes]
+ * @param {number} [options.maxJobs]
+ */
+export function createJobRegistry ({ ringBytes = RING_BYTES, maxJobs = MAX_JOBS } = {}) {
+  /** @type {Map<string, object>} */
+  const jobs = new Map()
+
+  /** Убрать старые завершённые: демон живёт неделями, память не резиновая. */
+  function evictFinished () {
+    const finished = [...jobs.values()]
+      .filter((job) => job.status !== 'running' && job.status !== 'stopping')
+      .sort((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0))
+    while (finished.length > MAX_FINISHED) {
+      const job = finished.shift()
+      jobs.delete(job.id)
+    }
+  }
+
+  function running () {
+    let count = 0
+    for (const job of jobs.values()) if (job.status === 'running' || job.status === 'stopping') count++
+    return count
+  }
+
+  /**
+   * Запустить команду в фоне.
+   * @param {object} options
+   * @param {string} options.command
+   * @param {string} [options.cwd]
+   * @param {string} [options.shell]
+   * @param {number} [options.timeout] секунды; 0 или пусто — без ограничения
+   * @returns {{ok: boolean, results?: object[], code?: string, message?: string}}
+   */
+  function start ({ command, cwd, shell, timeout, sandbox = null }) {
+    if (typeof command !== 'string' || !command.trim()) {
+      return { ok: false, code: 'bad_args', message: 'нужна команда' }
+    }
+    if (running() >= maxJobs) {
+      return { ok: false, code: 'too_many_jobs', message: `уже работает ${running()} процессов, потолок ${maxJobs}` }
+    }
+    const id = `job-${randomBytes(8).toString('hex')}`
+    // Задание идёт тем же путём, что и обычная команда: если политика узла
+    // требует песочницу, процесс запускается в ней. Иначе фоновый процесс был бы
+    // способом обойти политику одной строкой.
+    const prepared = commandArgv({ command, shell, sandbox })
+    if (prepared.error) return prepared.error
+    const child = spawn(prepared.argv[0], prepared.argv.slice(1), {
+      cwd: prepared.enforcement === 'bwrap' ? undefined : (cwd || process.cwd()),
+      env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: platform !== 'win32',
+    })
+    const job = {
+      id,
+      command,
+      cwd: cwd ?? null,
+      status: 'running',
+      sandbox: prepared.enforcement,
+      startedAt: Date.now(),
+      endedAt: null,
+      code: null,
+      chunks: [],
+      bytes: 0,
+      dropped: 0,
+      cursor: 0,
+      child,
+      timer: null,
+    }
+    const push = (type, text) => {
+      if (!text) return
+      const chunk = { at: job.bytes, type, text }
+      job.chunks.push(chunk)
+      job.bytes += Buffer.byteLength(text)
+      // вытесняем старое, но так, чтобы смещения оставались абсолютными
+      while (job.chunks.length > 1 && job.bytes - job.chunks[0].at > ringBytes) {
+        const removed = job.chunks.shift()
+        job.dropped += Buffer.byteLength(removed.text)
+      }
+    }
+    child.stdout?.on('data', (chunk) => push('stdout', String(chunk)))
+    child.stderr?.on('data', (chunk) => push('stderr', String(chunk)))
+    child.on('error', (error) => {
+      job.status = 'failed'
+      job.message = error.message
+      job.endedAt = Date.now()
+    })
+    child.on('close', (code, signal) => {
+      if (job.timer) clearTimeout(job.timer)
+      if (job.status === 'stopping') job.status = 'killed'
+      else if (job.status !== 'failed') job.status = 'completed'
+      job.code = code
+      job.signal = signal ?? null
+      job.endedAt = Date.now()
+      evictFinished()
+    })
+    if (Number(timeout) > 0) {
+      job.timer = setTimeout(() => killTree(child, 'SIGKILL'), Number(timeout) * 1000)
+      if (typeof job.timer.unref === 'function') job.timer.unref()
+    }
+    jobs.set(id, job)
+    return { ok: true, results: [{ type: 'text', text: JSON.stringify({ id, status: job.status }) }] }
+  }
+
+  /**
+   * Прочитать вывод начиная с абсолютного смещения.
+   * @param {string} id
+   * @param {number} [offset] по умолчанию — с того места, где модель остановилась
+   * @returns {{ok: boolean, results?: object[], code?: string, message?: string}}
+   */
+  function output (id, offset) {
+    const job = jobs.get(id)
+    if (!job) return { ok: false, code: 'no_such_job', message: `нет процесса ${id}` }
+    const from = Number.isFinite(Number(offset)) ? Number(offset) : job.cursor
+    const parts = job.chunks.filter((chunk) => chunk.at >= from)
+    const text = parts.map((chunk) => chunk.text).join('')
+    job.cursor = job.bytes
+    return {
+      ok: true,
+      results: [{
+        type: 'text',
+        text: JSON.stringify({
+          id: job.id,
+          status: job.status,
+          code: job.code ?? null,
+          signal: job.signal ?? null,
+          offset: job.bytes,
+          dropped: job.dropped,
+          tookMs: (job.endedAt ?? Date.now()) - job.startedAt,
+          sandbox: job.sandbox ?? 'none',
+          stdout: parts.filter((chunk) => chunk.type === 'stdout').map((chunk) => chunk.text).join(''),
+          stderr: parts.filter((chunk) => chunk.type === 'stderr').map((chunk) => chunk.text).join(''),
+        }),
+      }],
+    }
+  }
+
+  /** Попросить процесс завершиться, всей группой. */
+  function kill (id, signal = 'SIGTERM') {
+    const job = jobs.get(id)
+    if (!job) return { ok: false, code: 'no_such_job', message: `нет процесса ${id}` }
+    if (job.status !== 'running') {
+      return { ok: true, results: [{ type: 'text', text: JSON.stringify({ id, status: job.status, changed: false }) }] }
+    }
+    job.status = 'stopping'
+    killTree(job.child, signal)
+    return { ok: true, results: [{ type: 'text', text: JSON.stringify({ id, status: job.status, signal }) }] }
+  }
+
+  /** Что сейчас запущено и чем кончилось (последние завершённые тоже видны). */
+  function list () {
+    const items = [...jobs.values()].map((job) => ({
+      id: job.id,
+      status: job.status,
+      code: job.code ?? null,
+      command: job.command.slice(0, 200),
+      sandbox: job.sandbox,
+      bytes: job.bytes,
+      tookMs: (job.endedAt ?? Date.now()) - job.startedAt,
+    }))
+    return { ok: true, results: [{ type: 'text', text: JSON.stringify({ jobs: items }) }] }
+  }
+
+  /** Убить всё: нужно при остановке демона, иначе процессы переживут его. */
+  function stopAll () {
+    for (const job of jobs.values()) {
+      if (job.status === 'running' || job.status === 'stopping') {
+        job.status = 'stopping'
+        killTree(job.child, 'SIGTERM')
+      }
+    }
+  }
+
+  return { start, output, kill, list, stopAll, get size () { return jobs.size } }
+}

package/lib/onboard.mjs

@@ -0,0 +1,199 @@
+/**
+ * Мастер первичной настройки: `dshnc onboard`.
+ *
+ * Меню, а не поток вопросов, потому что настраивать приходится разное и в
+ * разном порядке: кто-то пришёл за политикой доступа, кто-то за автозапуском.
+ *
+ * Главное правило: **текущее значение — предложение по умолчанию**, а пустой
+ * ответ его сохраняет. Так мастер не ломает уже настроенный узел и не требует
+ * вспоминать, что там было.
+ *
+ * @module dsh-node-client/onboard
+ */
+
+/**
+ * Взять правила того сервера, к которому узел подключён.
+ *
+ * Политика хранится по адресам серверов, поэтому «текущий потолок» — это не
+ * `config.policy`, а `config.policy[url]`. Если серверов несколько, берём
+ * первый: мастер правит один узел за раз, а переносить правила между серверами
+ * он не умеет и не должен делать вид, что умеет.
+ *
+ * @param {object} config настройки клиента
+ * @returns {{url: string|null, policy: object}}
+ */
+export function pickPolicy (config) {
+  const entries = Object.entries(config?.policy ?? {})
+  if (!entries.length) return { url: null, policy: {} }
+  const [url, policy] = entries[0]
+  return { url, policy: policy ?? {} }
+}
+
+/** Ответ с подсказкой: пустой ввод оставляет прежнее значение. */
+async function askDefault (ask, question, current) {
+  const shown = current === null || current === undefined || current === ''
+    ? question
+    : `${question} [${current}]`
+  const answer = (await ask(`${shown}: `) ?? '').trim()
+  return answer === '' ? current : answer
+}
+
+/** Список через запятую ↔ массив. */
+function toList (value) {
+  if (Array.isArray(value)) return value
+  return String(value ?? '').split(',').map((item) => item.trim()).filter(Boolean)
+}
+
+/**
+ * Пункт меню «доступ»: имя, каталоги, режимы, кто отвечает на вопросы.
+ *
+ * @returns {Promise<object>} изменения, которые надо сохранить
+ */
+export async function askAccess ({ ask, print = () => {}, config, policy, url = null }) {
+  const patch = {}
+  // Мастер не просто спрашивает — он объясняет, что означает каждый ответ.
+  // Без этого человек отвечает «наугад», а потом не понимает, почему узел
+  // отказывает в записи или не задаёт вопросы.
+  print('Имя узла — это то, чем узел зовут в вызовах и что видно в админке.')
+  patch.name = await askDefault(ask, 'Имя узла', config.name ?? '')
+  patch.aliases = toList(await askDefault(ask, 'Алиасы через запятую', toList(config.aliases).join(', ')))
+  print('Каталог сессий — где клиент заводит рабочие каталоги для моделей.')
+  // каталоги клиент читает из политики сервера, если они там заданы, поэтому
+  // по умолчанию подставляем именно их, а не пустой корень конфига
+  const workdir = await askDefault(ask, 'Каталог сессий (абсолютный путь)', policy?.workdir ?? config.workdir ?? '')
+  print('Разрешённые каталоги — границы записи: всё вне них узлу недоступно на запись.')
+  const roots = await askDefault(
+    ask,
+    'Разрешённые каталоги через запятую',
+    toList(policy?.roots ?? config.roots).join(', '),
+  )
+  const modes = ['ro', 'rw', 'full']
+  print('Потолок прав — самый широкий режим, который узел разрешит вообще:')
+  print('  ro — только чтение, rw — запись внутри разрешённых каталогов, full — без песочницы.')
+  const max = await askDefault(ask, `Потолок прав (${modes.join('/')})`, policy?.max ?? 'rw')
+  print('Стартовый режим — в каком режиме команда запускается по умолчанию.')
+  print('  Он может быть уже потолка: тогда расширение требует разрешения человека.')
+  const base = await askDefault(ask, `Стартовый режим (${modes.join('/')})`, policy?.base ?? 'rw')
+  print('Кто отвечает на вопрос «разрешить шире?»:')
+  print('  local — человек за этой машиной (окно на узле), server — человек в DSH, none — не спрашивать.')
+  const approver = await askDefault(ask, 'Кто отвечает на вопросы: local/server/none', policy?.approver ?? 'none')
+
+  // и каталоги, и режимы пишем в раздел этого сервера: раннер собирает общие
+  // значения из корня и накрывает их политикой сервера, поэтому корень без
+  // политики выглядел бы «настроил и не работает»
+  const next = { max, base, approver, roots: toList(roots), workdir }
+  if (approver === 'local') {
+    const current = policy?.ask?.local?.tool?.command ?? ''
+    print('Команда вопроса — чем на этой машине спросить человека. Подойдёт любой')
+    print('  инструмент, который возвращает 0 на «да»:')
+    print('    zenity --text-info --width=600 --title=dsh-nodes')
+    print('    kdialog --textinputbox "dsh-nodes"')
+    print('    notify-send ... && свой скрипт, который ждёт ответа')
+    print('  Текст вопроса уходит в stdin, если в команде нет %s.')
+    const tool = await askDefault(ask, 'Команда вопроса (пусто — не спрашивать)', current)
+    next.ask = tool
+      ? { local: { enabled: true, tool: { type: 'external', command: tool } } }
+      : { local: { enabled: false } }
+  }
+  // правила пишем в тот сервер, который настраиваем: иначе они окажутся нигде
+  patch.policy = url
+    ? { ...(config.policy ?? {}), [url]: { ...(config.policy?.[url] ?? {}), ...next } }
+    : (config.policy ?? {})
+  return patch
+}
+
+/** Пункт меню «связь»: опрос и пинг по сокету. */
+export async function askConnection ({ ask, print = () => {}, config }) {
+  // Для новой настройки предлагаем рабочие значения: сокет, умерший молча,
+  // иначе замечается только по TCP. Ноль — это осознанный выбор «выключить»,
+  // и он сохраняется как есть, а не подменяется умолчанием.
+  const hasPing = config.pingInterval !== undefined
+  print('Периодический опрос — страховка, если сокет не поднялся. Ноль выключает.')
+  print('Пинг по сокету — проверка «сервер слышит меня»: 15 с и растяжение до 10 раз,')
+  print('  когда сервер давно ничего не присылал. Ноль выключает пинг совсем.')
+  return {
+    pollIdleMs: Number(await askDefault(ask, 'Периодический опрос, мс (0 — только события)', config.pollIdleMs ?? 0)) || 0,
+    pingInterval: Number(await askDefault(ask, 'Пинг по сокету, с (0 — выключен)', config.pingInterval ?? (hasPing ? 0 : 15))) || 0,
+    maxPingIntervalFactor: Number(await askDefault(ask, 'Во сколько раз растягивать пинг без работы (0 — не растягивать)', config.maxPingIntervalFactor ?? (hasPing ? 0 : 10))) || 0,
+  }
+}
+
+/** Показать, что получилось: перед записью человек должен увидеть итог. */
+export function renderConfig (config) {
+  const plain = { ...config }
+  delete plain.servers
+  delete plain.id
+  return JSON.stringify(plain, null, 2)
+}
+
+/**
+ * Цикл меню.
+ *
+ * @param {object} options
+ * @param {(question: string) => Promise<string>} options.ask
+ * @param {(text: string) => void} options.print
+ * @param {() => object} options.load свежие настройки
+ * @param {(patch: object) => object} options.save сохранить и вернуть итог
+ * @param {(config: object) => Promise<void>} options.autostart запуск мастера автозапуска
+ * @param {() => string[]} [options.status] строки состояния для шапки
+ */
+export async function runOnboard ({ ask, print, load, save, autostart, status = () => [] }) {
+  for (;;) {
+    const config = load()
+    print('')
+    for (const line of status(config)) print(line)
+    print('')
+    print('Мастер настройки: спрашивает по одному разделу и объясняет, что к чему.')
+    print('Текущее значение стоит в скобках; пустой ответ его не меняет.')
+    print('')
+    print('1) доступ: имя, каталоги, режимы, кто отвечает на вопросы')
+    print('2) связь: опрос, пинг по сокету')
+    print('3) автозапуск: systemd-юнит')
+    print('4) показать конфиг')
+    print('0) выход')
+    const choice = (await ask('Что настроить? ') ?? '').trim()
+    if (choice === '0' || choice === '') return
+
+    if (choice === '1') {
+      const { url, policy } = pickPolicy(config)
+      if (!url) {
+        print('Сначала подключись к серверу: dshnc connect <ссылка>. Без сервера')
+        print('правила доступа писать некуда — они живут в разделе этого сервера.')
+        continue
+      }
+      print(`Правила для ${url}`)
+      const patch = await askAccess({ ask, print, config, policy, url })
+      // показываем итог ДО записи: предпросмотр не должен ничего сохранять
+      print('')
+      print('Итог:')
+      print(renderConfig({ ...config, ...patch }))
+      const ok = (await ask('Записать? [Y/n] ') ?? '').trim().toLowerCase()
+      if (ok === '' || ok === 'y' || ok === 'да') {
+        save(patch)
+        print('сохранено')
+      } else {
+        print('не записано')
+      }
+      continue
+    }
+
+    if (choice === '2') {
+      const patch = await askConnection({ ask, print, config })
+      save(patch)
+      print('сохранено')
+      continue
+    }
+
+    if (choice === '3') {
+      await autostart(load())
+      continue
+    }
+
+    if (choice === '4') {
+      print(renderConfig(load()))
+      continue
+    }
+
+    print('нет такого пункта')
+  }
+}

package/lib/ping-policy.mjs

@@ -0,0 +1,49 @@
+/**
+ * Когда клиент пингует сервер по сокету и с какой паузой.
+ *
+ * Логика целиком в одной чистой функции, чтобы её можно было проверить тестом
+ * без сети: расписание — это арифметика, а не побочный эффект.
+ *
+ * Правила:
+ *  - пинг отправляется через `pingInterval` после последнего успешного
+ *    общения (`lastSeen`);
+ *  - если сервер давно не присылал команд (`lastCommand`), пауза растёт:
+ *    первые пять интервалов она обычная, потом ×2, ×3 … но не больше
+ *    `maxPingIntervalFactor`;
+ *  - ответа нет в течение интервала — это разрыв, нужен реконнект.
+ *
+ * @module dsh-node-client/ping-policy
+ */
+
+/** После скольких интервалов без команд пауза начинает расти. */
+export const GROW_AFTER_TICKS = 5
+
+/**
+ * Во сколько раз растянуть паузу.
+ *
+ * @param {object} options
+ * @param {number} options.ticks сколько интервалов прошло без новых команд
+ * @param {number} [options.factor] потолок растяжения; 0 или меньше — не растягивать
+ * @returns {number} множитель, всегда >= 1
+ */
+export function pingMultiplier ({ ticks, factor = 0 }) {
+  const cap = Number(factor) > 0 ? Number(factor) : 1
+  if (ticks < GROW_AFTER_TICKS) return 1
+  // 5 тиков → ×2, 6 → ×3, и так до потолка
+  return Math.min(2 + (ticks - GROW_AFTER_TICKS), cap)
+}
+
+/**
+ * Пауза до следующего пинга в миллисекундах.
+ *
+ * @param {object} options
+ * @param {number} options.pingInterval секунды из конфига; 0 или меньше — выключено
+ * @param {number} [options.factor] потолок растяжения
+ * @param {number} [options.ticks] интервалов без команд
+ * @returns {number} миллисекунды; 0 означает «пинг выключен»
+ */
+export function pingDelay ({ pingInterval, factor = 0, ticks = 0 }) {
+  const base = Number(pingInterval)
+  if (!Number.isFinite(base) || base <= 0) return 0
+  return Math.round(base * pingMultiplier({ ticks, factor }) * 1000)
+}