Інженерні нотатки Naly: блокування машинного cron і спостережувані пайплайни публікації

Анотація

TL;DRNaly використовує машинний cron як невеликий, але продуманий планувальник: обгортки з часовими мітками запускають завдання публікації та дистрибуції, flock запобігає накладанню запусків, ініціалізація зі спрощеним runtime робить середовище явним, а зовнішні логи плюс детерміновані артефакти перетворюють кожне виконання на доказ. Теза в тому, що проста автоматизація на рівні хоста може бути production-grade, коли конкурентність, відтворюваність і спостережуваність спроєктовані як першокласні результати, а не як shell-додатки після факту.

Машинний cron не є workflow-рушієм. Він не знає, чи була стаття опублікована, blob завантажений, запис у базу даних ідемпотентний або downstream-сповіщення безпечне для надсилання. Його завдання вужче: прокинутися у передбачуваний час і виконати команду. Дизайн Naly залишає цей контракт малим і будує шар надійності навколо нього.

Корисний шаблон такий schedule -> locked wrapper -> explicit runtime -> observable artifact. Cron забезпечує годинник. flock забезпечує захист одного запуску на одному хості. Обгортка забезпечує завантаження середовища, вибір режиму, логування та дисципліну exit-code. Прикладний скрипт забезпечує доменну поведінку. Каталог артефактів забезпечує аудиторський слід.

Де це розміщено в Naly

Щоденний пайплайн публікації Naly є частиною системи зростання користувачів: він підтримує регулярні статті, перевірки дистрибуції та smoke-mode верифікацію для роботи, яка має створювати цінність для залучення або утримання. Сам розклад навмисно винесено за межі request path Next.js. Рендер сторінки не має відповідати за рішення про існування сьогоднішнього завдання публікації.

На високому рівні пайплайн має п’ять меж:

Запис crontab містить розклад і називає одну обгортку.
Обгортка створює run id, обирає повний або smoke-режим і прив’язує місця для логів та артефактів.
flock охороняє критичну секцію, щоб повільний запуск не перекрив наступний запланований слот.
Runtime TypeScript виконує checked-in завдання з явним завантаженням середовища.
Завдання записує детерміновані артефакти, статус і логи за межами runtime-дерева репозиторію.

Вибір зовнішнього log-root має значення. Naly зберігає runtime-логи поза репозиторієм, з NALY_LOG_ROOT=/tmp/logs за замовчуванням і /data/logs для persistent-середовищ. Це зберігає репозиторій як джерело і довговічну пам’ять проєкту, тоді як логи живуть в операційному просторі імен, призначеному для ротації, зберігання та перевірки.

Детермінований каталог артефактів є другою половиною спостережуваності. Рядок логу каже, що сталося; шлях до артефакта доводить, який output було створено. Для щоденного job статті каталог артефактів має ключуватися назвою job, date label, schedule slot і run id, а потім містити стартові metadata, фінальні metadata, stdout/stderr, content outputs, smoke outputs і будь-які publish identifiers.

Технічний механізм

Linux crontab(5) контракт прямий: crontab містить інструкції для cron daemon виконати команду у відповідний час. Manual також документує деталі, важливі в production: cron задає розріджене середовище, зокрема SHELL, HOME, і LOGNAME; CRON_TZ може визначати інтерпретацію розкладу; символи percent у командах мають спеціальну поведінку stdin; переходи на літній час можуть пропускати або дублювати відповідні job; а записи cron потребують коректного завершення newline.

Саме тому Naly трактує рядки cron як вузькі launchers, а не як application logic. Частина команди має бути нудною: вказати на обгортку, не робити inline TypeScript, не робити крихкої гімнастики з quoting і залишити прикладну поведінку checked-in скриптам.

Корисна ментальна модель така:

cron tick
  -> wrapper starts with sparse runtime
  -> run_id and artifact_dir are assigned
  -> log files are opened under NALY_LOG_ROOT
  -> local file lock is acquired
  -> environment is loaded explicitly
  -> checked-in TypeScript job runs
  -> manifest, status, outputs, and exit code are finalized

flock(1) є примітивом конкурентності. Його manual описує command-line tool, який керує file locks із shell scripts, обгортаючи виконання іншої команди. Він підтримує exclusive locks за замовчуванням, nonblocking acquisition з -n, bounded waiting з -w, conflict exit codes з -E, і propagation child exit-code, коли wrapped command виконується. Цих деталей достатньо, щоб закодувати політику: skip, wait або fail visibly.

Для Naly lock key має відповідати домену ідемпотентності. Daily article publisher і distribution sender можуть потребувати окремих locks, якщо вони можуть безпечно виконуватися незалежно. Два article publishers, які записують той самий date-labeled output, потребують того самого lock. Назви locks мають бути стабільними та локальними для машини, а не зберігатися на шляхах NFS або CIFS, тому що flock manual зазначає обмежену поведінку на деяких network filesystems.

Далі спостережуваність наслідує форму OpenTelemetry, навіть коли реалізація легша за повний collector. OpenTelemetry визначає signals як output системи, що використовується для спостереження за underlying activity, включно з traces, metrics, logs і baggage. Для cron-публікації trace — це lifecycle запуску, metrics — durations і counts, logs — event records, а baggage-like context — run id, mode, schedule slot, artifact directory і version metadata, що проходять через кожен крок.

Що каже література

Свіжа робота arXiv прямо говорить про ризик cron-style автоматизації. Стаття Agrawal і Jain 2026 року про resilient ELT pipelines повідомляє, що ad-hoc ingestion scripts, включно з cron jobs, створювали silent failures і data gaps, які підривали довіру. Їхній запропонований remedy — важча DAG orchestration, immutable raw history і state-based dependency management. Naly не потребує всієї цієї machinery для кожного daily publishing job, але переймає головний урок: scheduled pipeline має залишати durable state, який робить тишу підозрілою.

Робота Albuquerque і Correia 2025 року про tracing and metrics design patterns стверджує, що distributed systems стає важче діагностувати, коли observability фрагментується. Вони розділяють distributed tracing, application metrics і infrastructure metrics як окремі design patterns. Для cron wrappers Naly це перетворюється на практичне правило: не дозволяти stdout бути єдиним доказом. Publish run потребує run trace, application-level counters і host-level context.

AgentTrace релевантний, тому що publishing pipeline Naly включає AI-assisted components. AlSayyad, Huang і Pal подають structured logging як runtime accountability layer для agent systems, фіксуючи operational і contextual behavior, щоб nondeterministic execution можна було audited. Версія Naly має уникати витоку private reasoning, але має записувати prompt class, source set identifiers, model/runtime metadata, safety mode, artifact hashes і publish decisions.

OpsAgent, переглянутий у May 2026, підсилює той самий operational point з incident management: metrics, logs і traces стають кориснішими, коли перетворюються на structured, auditable descriptions. Це важливо і для малого cron pipeline. Мета не в тому, щоб зібрати більше тексту; мета — зробити наступну діагностику швидшою, ніж читання terminal transcript.

Компроміси дизайну

Cron plus file locks навмисно скромний. У нього менше рухомих частин, ніж у workflow platform, немає central scheduler database, web UI і built-in DAG semantics. Це сила, коли job — single-machine daily publisher із чітким runtime contract. Це слабкість, коли jobs стають distributed, dependency-heavy або потребують high-cardinality retry policies.

File locks також за своєю природою локальні. Вони добре підходять для одного хоста й однієї filesystem. Вони є поганою заміною database advisory locks, queue leases або orchestration state, якщо кілька machines можуть запускати той самий publisher. Поточне використання Naly — host-level automation; якщо publishing стане multi-runner, locking boundary має перейти у shared durable state.

Зовнішні логи обмінюють зручність на operational hygiene. Запис логів у repo робить local debugging зручним, але забруднює source control і приховує проблеми rotation. Використання /tmp/logs або /data/logs змушує систему оголосити, які logs disposable, а які persistent.

Smoke mode — ще один компроміс. Smoke run має бути дешевим і non-destructive, але він має виконувати ту саму wrapper, lock, environment loading і artifact code, що й full run. Якщо smoke mode обходить складні частини, він стає placebo.

Детерміновані артефакти коштують disk space і cleanup work. Виграш — replayability: operators можуть порівняти два runs, знайти точний generated output і відрізнити publishing failure від distribution failure без реконструкції state з пам’яті.

Режими відмови

Перший режим відмови — overlap. Job, який зазвичай триває три хвилини, зрештою триває тридцять, і наступний cron tick запускає ще одну копію. flock запобігає цьому лише якщо кожен entry використовує той самий lock key, тримає lock протягом усієї critical section і випадково не дозволяє background children продовжуватися поза guarded lifecycle.

Другий режим відмови — misleading schedule. Daylight-saving transitions можуть пропускати або дублювати jobs. Field-step syntax можна неправильно прочитати. Percent characters можуть змінити command stdin. Відсутній newline може залишити crontab частково зламаним. Defensive posture — UTC scheduling, мінімальний cron command text і wrapper-level schedule-slot recording.

Третій режим відмови — sparse runtime drift. Non-interactive shell cron може не мати того самого PATH, Node version, package-manager path, secrets або locale, що й interactive session. Stripped-runtime bootstrap Naly робить це явним: завантажити required environment в обгортці, а потім запускати checked-in TypeScript scripts через tsx, а не inline code.

Четвертий режим відмови — silent success. Скрипт може завершитися з zero exit, створивши zero publishable artifacts. Обгортка має трактувати expected output counts, final manifest presence і publish identifiers як completion checks. Success — це не просто відсутність exception; success — це coherent final state.

П’ятий режим відмови — partial publish. Database row може існувати без blob, blob може існувати без public article, або distribution message може посилатися на unpublished URL. Deterministic manifests допомагають, розділяючи prepared, committed, published і distributed states.

Шостий режим відмови — failure самої observability. Якщо log root відсутній, заповнений або unwritable, обгортка має fail before irreversible work. Якщо artifact finalization fails, це має бути failed run, навіть якщо content step succeeded, бо audit trail є частиною product surface.

Нотатки щодо реалізації

Використовуйте одну wrapper на operational job family. Запис crontab має виражати schedule, timezone і wrapper path; wrapper має володіти всіма іншими concern. Це включає run_id, mode, artifact_dir, log_path, lock acquisition, environment loading, runtime launch і final status.

Використовуйте один lock на idempotency boundary. Daily article job не має ділити lock з unrelated maintenance work, але кожен path, який може publish той самий daily article, має ділити один lock. Віддавайте перевагу bounded waits або nonblocking exits замість unbounded queueing, а потім записуйте, чи run executed, skipped або timed out.

Робіть artifact directories детермінованими. Практична форма — job/YYYY-MM-DD/schedule-slot/run-id/. Покладіть started.json на початку і finished.json в кінці. Включайте mode, date label, commit або build identifier, коли доступні, package/runtime family, duration, exit code, output counts і publish identifiers.

Тримайте smoke і full modes на одній рейці. Smoke mode може писати в dry-run namespace і suppress public distribution, але він усе одно має acquire the lock, load the environment, initialize Drizzle або Neon access, коли потрібно, verify blob-write assumptions, коли релевантно, і render markdown через той самий content path.

Використовуйте structured logs, навіть коли пишете plain files. Кожна важлива event має включати job, run id, mode, schedule slot, artifact directory, duration або timestamp, і result. Це робить log files придатними для query later і зберігає дизайн compatible з OpenTelemetry-style ingestion, якщо Naly пізніше додасть collector.

Поточний runtime stack відповідає цьому шаблону. tsx і TypeScript підтримують checked-in operational scripts. Drizzle ORM і Neon підтримують durable database state. Vercel Blob підтримує durable publish artifacts. marked підтримує markdown rendering paths. Next.js і React показують результат, але cron має залишатися поза request lifecycle.

Ширший урок у тому, що cron безпечний лише тоді, коли його не просять пам’ятати. Naly змушує cron будити систему, flock серіалізувати risky region, а artifacts — пам’ятати, що сталося.