badmfck-api-server 5.0.3 → 5.0.5

package/bluegreen.help.md

@@ -0,0 +1,277 @@
+# Blue-green в badmfck-api-server
+
+Как устроена выкладка без простоя и как приложение узнаёт, работает ли оно сейчас в проде.
+
+---
+
+## 1. Идея в двух словах
+
+У проекта **два слота** — `blue` и `green`. Каждый слот — это отдельная папка и отдельный pm2-процесс на своём порту. Трафик в каждый момент идёт **только в один** из них: nginx смотрит на порт активного слота.
+
+- **Deploy** выкладывает новую версию в **неактивный** слот. Прод при этом не трогается.
+- **Activate** переключает nginx на выложенный слот. Переключение мгновенное, без простоя.
+- **Rollback** — это тот же activate, но на предыдущий слот. Старая версия всё ещё запущена, поэтому откат занимает секунды.
+
+---
+
+## 2. Что где лежит на сервере
+
+| Что | Где | Кто меняет |
+|---|---|---|
+| Код слотов | `<destination>/blue`, `<destination>/green` | деплоер при deploy |
+| pm2-процессы | `<name>-blue`, `<name>-green` | деплоер при deploy |
+| Состояние проекта | `<projects_path>/<name>_state_.json` | деплоер при deploy / activate |
+| Порт активного слота для nginx | `<nginx.config_dir>/<name>.upstream.conf` | деплоер, **переписывает** при каждом activate |
+| Серверный конфиг nginx | `<nginx.config_dir>/<name>.server.conf` | деплоер создаёт **один раз**, дальше им владеет devops (SSL через certbot и т.п.) |
+| Паспорт слота для приложения | `<destination>/<slot>/.bluegreen.json` (права `600`) | деплоер при deploy, пишет в **оба** слота |
+
+Файл состояния:
+
+```jsonc
+{
+  "active": "blue",          // куда сейчас идёт трафик
+  "lastDeployed": "green",   // куда была последняя выкладка
+  "history": [ { "slot": "green", "action": "deploy", "user": "igor", "at": 1789… } ],  // последние 200
+  "statusToken": "…"         // read-only токен для приложений, см. раздел 6
+}
+```
+
+Если `lastDeployed ≠ active`, значит новая версия выложена, но ещё не включена.
+
+---
+
+## 3. Жизненный цикл
+
+**Первый деплой проекта:** слот `blue` создаётся **сразу активным**: `active = lastDeployed = blue`, nginx настраивается на него.
+
+**Каждый следующий деплой:**
+1. Деплоер выбирает слот, противоположный активному (active `blue` → выкладка в `green`).
+2. Распаковывает архив, делает `npm ci`, пишет конфиг, запускает `<name>-green`.
+3. **nginx не трогается** — трафик продолжает идти в `blue`.
+4. Можно проверить `green` напрямую по его порту.
+
+**Activate:**
+1. `active` становится `green`.
+2. `upstream.conf` переписывается на порт `green`.
+3. Выполняется хук `on_switch`, обычно `nginx -s reload`.
+4. `blue` **продолжает работать** — это и есть готовый откат.
+
+**Rollback:** `badmfck activate blue` возвращает трафик на `blue`.
+
+> Если в ответе activate пришло «SLOT FLIPPED BUT nginx RELOAD FAILED», состояние уже переключено, упал только reload. Перезапусти его вручную: `nginx -s reload`.
+
+---
+
+## 4. Настройка проекта на деплоере
+
+Конфиг проекта в `projects_path`:
+
+```jsonc
+{
+  "name": "gateway",
+  "destination": "/var/node/gateway",
+  "token": "…",
+  "unpack": true, "install": true, "pm2": true,
+
+  // Общие значения для обоих слотов (БД, домены, флаги)
+  "config": { "DB_HOST": "…" },
+
+  "bluegreen": {
+    // Отличия слотов. Слот побеждает при совпадении ключей.
+    // Порт обязателен (ключ port / PORT, регистр не важен) и у слотов должен различаться.
+    "blue_config":  { "port": "8055" },
+    "green_config": { "port": "8056" },
+
+    // Выполняется после каждого переключения. Путь к бинарнику — абсолютный.
+    "on_switch": ["/usr/sbin/nginx", "-s", "reload"],
+
+    // Опционально: разные флаги pm2 для слотов
+    "blue_pm2_attributes":  ["--cron-restart", "10 0 * * *"],
+    "green_pm2_attributes": ["--cron-restart", "10 0 * * *"]
+  },
+
+  "nginx": {
+    "config_dir": "/var/node-nginx-configs",   // nginx должен делать include /var/node-nginx-configs/*.conf
+    "domain": "gateway.example.com"
+  }
+}
+```
+
+В `setup.json` деплоера можно указать `status_url` — адрес, по которому приложения спрашивают свой статус. Нужен **только** если деплоер не слушает `127.0.0.1` (подробнее в разделе 6).
+
+---
+
+## 5. CLI в проекте
+
+`package.json` проекта:
+
+```json
+"scripts": {
+  "deploy":       "badmfck deploy",
+  "activate":     "badmfck activate",
+  "rollback:blue":  "badmfck activate blue",
+  "rollback:green": "badmfck activate green",
+  "status":       "badmfck status"
+}
+```
+
+| Команда | Что делает |
+|---|---|
+| `npm run deploy` | сборка и выкладка в неактивный слот |
+| `npm run activate` | включить последний выложенный слот |
+| `badmfck activate blue` / `green` | включить конкретный слот (rollback) |
+| `npm run status` | какой слот активен, какой выложен последним, ждёт ли что-то переключения, кто и когда это делал |
+
+**Где CLI берёт конфиг.** Сначала папка `deploy/` (если там несколько конфигов, CLI спросит, какой взять), потом файл `deploy.json`. Путь можно указать явно, но через npm нужен разделитель `--`:
+
+```bash
+npm run deploy -- deploy/prod.json
+npm run activate -- deploy/prod.json blue
+```
+
+---
+
+## 6. Приложение: «я сейчас в проде?»
+
+### Главное понятие — `live`
+
+У каждого процесса есть `live`: **должен ли он работать как живой экземпляр**.
+
+| Ситуация | `live` |
+|---|---|
+| Проект **не** на blue-green | `true` — единственный экземпляр всегда живой |
+| Blue-green, мой слот активен | `true` |
+| Blue-green, мой слот в резерве (standby) | `false` |
+| Ответа от деплоера ещё не было | `null` — ждать, не угадывать |
+
+Логика, написанная через `live`, **не меняется** при переходе проекта на blue-green: сегодня она просто получает `true`.
+
+### Основной способ — `onLiveChange`
+
+```ts
+import { APIService } from "badmfck-api-server";
+
+APIService.onLiveChange(live => {
+  if (live) startCrons();   // запустить синглтон-работу
+  else      stopCrons();    // я в резерве — остановиться
+});
+```
+
+- Если ответ уже известен, колбэк вызывается **сразу**. Дальше — только когда `live` **меняется** (activate, rollback). Не важно, подписался код до первой проверки или после.
+- С неизвестным значением колбэк **не вызывается никогда**.
+- Проект не на blue-green: колбэк вызовется **один раз** с `true`.
+- Возвращает функцию отписки.
+
+### Синхронная проверка — для горячего пути
+
+```ts
+if (APIService.isLive) { … }          // true / false / null, без I/O
+const s = APIService.blueGreenState;  // полное последнее известное состояние или null
+```
+
+### Прочее
+
+```ts
+// Сырой результат прямо сейчас (может вернуть isActive: null при сбое). Кешируется на 10 с.
+const s = await APIService.getBlueGreenActiveState({ force: true });
+
+// Низкоуровневый сигнал: срабатывает при любой смене live / isActive / active
+import { S_BLUEGREEN_STATE_CHANGED } from "badmfck-api-server";
+S_BLUEGREEN_STATE_CHANGED.subscribe(({ current, previous }) => { … });
+```
+
+Поля состояния:
+
+| Поле | Значение |
+|---|---|
+| `live` | на что ветвиться (см. выше) |
+| `bluegreen` | выложено ли приложение как blue-green слот |
+| `project`, `slot` | проект и мой слот |
+| `active` | активный слот по данным деплоера |
+| `isActive` | `slot === active` |
+| `lastDeployed`, `readyToSwitch` | последний выложенный слот / ждёт ли он переключения |
+| `stale` | последняя проверка не удалась, показано последнее известное значение |
+| `error` | почему проверка не удалась |
+
+### Настройка
+
+```ts
+new APIService({ …, blueGreenWatchMs: 5000 })   // по умолчанию 5000; 0 — выключить наблюдатель
+```
+
+Наблюдатель запускается сам после старта сервера. Если приложение выложено не через blue-green, он останавливается после первой проверки. Если наблюдатель выключен, `isLive` / `blueGreenState` обновляются только при ручном вызове `getBlueGreenActiveState()`.
+
+### Как это работает под капотом
+
+1. При деплое деплоер кладёт в папку каждого слота `.bluegreen.json`: имя проекта, слот, адрес для запроса статуса и **read-only токен**.
+2. Приложение ищет этот файл вверх от папки entry-скрипта. Путь можно задать явно через env `BLUEGREEN_FILE`.
+3. Приложение спрашивает деплоер `POST …/pckg/slot` по `127.0.0.1` (деплоер всегда на той же машине) и получает активный слот.
+4. Деплоер читает файл состояния на каждый запрос, поэтому **activate виден сразу**, рестарт не нужен.
+
+### Надёжность
+
+- **Сбой деплоера не переводит приложение в резерв.** Неудачная проверка сохраняет последнее известное значение (`stale: true`) и **не** вызывает `onLiveChange`.
+- **Битый `.bluegreen.json`** даёт `live: null`, колбэк не вызывается. Считать такой слот живым опасно: синглтон-работа может пойти дважды.
+- Методы **никогда не бросают** исключения.
+- Нагрузка: не больше 1 запроса за 5–10 с на процесс, по loopback. Запросы не пишутся в netlog деплоера и не попадают в статистику исходящих запросов приложения.
+
+### Безопасность
+
+- `statusToken` даёт **только** право узнать активный слот. Токен деплоя и логин/пароль деплоера в приложение не попадают.
+- `.bluegreen.json` создаётся с правами `600`.
+- `pckg/slot` отвечает одинаковым 401 на неизвестный проект и на неверный токен (перебором проекты не узнать). Имя проекта строго валидируется, токен сравнивается за константное время.
+
+---
+
+## 7. Что зависит от `live`, а что нет
+
+**Запускать только при `live === true`:**
+- кроны и планировщики;
+- рассылки и уведомления;
+- потребители очередей, которые должны быть в единственном экземпляре;
+- фоновые задачи, пишущие общее состояние (прогрев общих кешей, агрегации).
+
+**Не зависят от `live`:**
+- HTTP-обработчики: трафик и так идёт только в активный слот через nginx, а резервный слот нужно уметь проверить по его порту;
+- эндпоинты liveness / readiness / мониторинга.
+
+**⚠️ База данных общая для обоих слотов.** Новая версия стартует и работает параллельно со старой ещё **до** переключения, а после отката старая версия снова работает с базой. Поэтому:
+- миграции схемы должны быть **обратно совместимыми**: сначала добавить новое, удалить старое — отдельной выкладкой позже;
+- миграцию, которую нельзя запускать дважды, выполняй только на живом слоте или отдельным шагом.
+
+---
+
+## 8. Переход обычного проекта на blue-green (вручную)
+
+1. Задай в `blue_config` / `green_config` порты, **отличные** от текущего порта приложения.
+2. Добавь в конфиг проекта блоки `bluegreen` и `nginx` (раздел 4).
+3. Выполни первый деплой. Поднимется `<name>-blue` в `<destination>/blue`, и nginx переключится на него.
+4. Проверь, что сервис отвечает через домен и что `npm run status` показывает `active: BLUE`.
+5. **Останови старый процесс:** `pm2 delete <name>`, затем `pm2 save`.
+
+> Пятый шаг обязателен. Деплоер старый процесс **не** останавливает. Над ним нет `.bluegreen.json`, поэтому он продолжит считать себя `live: true`, и синглтон-работа будет выполняться **дважды**.
+
+Код приложения можно готовить заранее, ещё до перехода: `onLiveChange` на обычном проекте просто вернёт `true`.
+
+---
+
+## 9. Диагностика
+
+| Симптом | Причина | Что делать |
+|---|---|---|
+| `bluegreen: false` на blue-green проекте | слот выложен **до** появления этой функции, `.bluegreen.json` нет | выполнить один деплой: файл запишется в оба слота |
+| `live: null`, в `error` «malformed» | `.bluegreen.json` повреждён | передеплоить слот |
+| `live: null`, `error` «deployer unreachable» | деплоер недоступен, а прошлого значения ещё нет | проверить деплоер; если он не слушает loopback — задать `status_url` в его `setup.json` |
+| `stale: true` | деплоер временно недоступен | ничего: работаем на последнем известном значении |
+| `error` «deployer rejected… Invalid project or status token» | токен в файле не совпадает с state-файлом | передеплоить слот |
+| После activate приложение ещё несколько секунд видит старый слот | интервал опроса | нормально; для мгновенной проверки — `getBlueGreenActiveState({ force: true })` |
+| Синглтон-работа выполняется дважды после перехода на blue-green | работает старый процесс без слота | `pm2 delete <name>` (раздел 8) |
+
+Проверка на сервере вручную:
+
+```bash
+cat <projects_path>/<name>_state_.json                # active / lastDeployed / history
+cat <nginx.config_dir>/<name>.upstream.conf           # куда реально смотрит nginx
+cat <destination>/<slot>/.bluegreen.json              # паспорт слота
+pm2 list | grep <name>                                # оба слота запущены?
+```

package/dist/apiServer/APIService.d.ts

@@ -5,6 +5,8 @@ import { HTTPRequestVO, IError, TransferPacketVO } from './structures/Interfaces
 import Signal, { Req } from "badmfck-signal";
 import http from 'http';
 import { IDeployerServiceOptions } from './deployment/DeployerService';
+import { IBlueGreenState, IBlueGreenStateOptions } from './deployment/BlueGreenState';
+import { ILogFilesOptions } from './monitor/LogFiles';
 export interface IMonitorUser {
     login: string;
     password: string;
@@ -52,6 +54,8 @@ export interface APIServiceOptions<TInterceptor = unknown> {
     fileTempDir: string;
     fileLimit: number;
     metricsDir?: string;
+    blueGreenWatchMs?: number;
+    logFiles?: ILogFilesOptions;
 }
 type InferInterceptor<T> = T extends IInterceptor<infer U> ? U : unknown;
 export declare const getDefaultOptions: <I extends IInterceptor<any> | undefined>(overrides?: Omit<Partial<APIServiceOptions<InferInterceptor<NonNullable<I>>>>, "interceptor"> & {
@@ -69,6 +73,10 @@ export declare const REQ_DOC_USERS: Req<void, IDocumentationUser[]>;
 export declare const S_APP_STARTED: Signal<void>;
 export declare function Initializer(services: IBaseService[]): Promise<void>;
 export declare class APIService<TInterceptorResult = any, TInternalCallParams = any> extends BaseService {
+    static getBlueGreenActiveState(opts?: IBlueGreenStateOptions): Promise<IBlueGreenState>;
+    static get blueGreenState(): IBlueGreenState | null;
+    static get isLive(): boolean | null;
+    static onLiveChange(cb: (live: boolean, state: IBlueGreenState) => void): () => void;
     private version;
     private options;
     private monitor;

package/dist/apiServer/APIService.js

@@ -60,6 +60,7 @@ const DocumentService_1 = require("./DocumentService");
 const Documentation_1 = require("./documentation/Documentation");
 const MicroserviceHostController_1 = require("./external/MicroserviceHostController");
 const DeployerService_1 = require("./deployment/DeployerService");
+const BlueGreenState_1 = require("./deployment/BlueGreenState");
 const Deployer_1 = require("./deployment/Deployer");
 let nextLogID = 0;
 function defaultOptions() {
@@ -120,6 +121,18 @@ async function Initializer(services) {
     }
 }
 class APIService extends BaseService_1.BaseService {
+    static getBlueGreenActiveState(opts) {
+        return (0, BlueGreenState_1.getBlueGreenActiveState)(opts);
+    }
+    static get blueGreenState() {
+        return (0, BlueGreenState_1.getBlueGreenStateSync)();
+    }
+    static get isLive() {
+        return (0, BlueGreenState_1.getBlueGreenStateSync)()?.live ?? null;
+    }
+    static onLiveChange(cb) {
+        return (0, BlueGreenState_1.onLiveChange)(cb);
+    }
     version = PACKAGE_VERSION;
     options;
     monitor = null;
@@ -158,7 +171,11 @@ class APIService extends BaseService_1.BaseService {
         this.options.endpoints.push(new ExternalServiceEndpoint_1.ExternalServiceEndpoint());
         this.options.endpoints.push(new MicroserviceHostController_1.MicroserviceHostController());
         if (this.options.deployer && this.options.deployer.projects_path && this.options.deployer.setup_path) {
-            this.deployer = new DeployerService_1.DeployerService(this.options.deployer);
+            this.deployer = new DeployerService_1.DeployerService({
+                ...this.options.deployer,
+                selfPort: this.options.port,
+                selfBaseEndPoint: this.options.baseEndPoint,
+            });
             this.deployer.init();
             this.options.endpoints = [
                 new Deployer_1.Deployer(),
@@ -467,6 +484,7 @@ class APIService extends BaseService_1.BaseService {
         });
         server.listen(this.options.port, () => {
             (0, LogService_1.logAPI)('${APIService.js}', 'API Service started at: ' + this.options.port + ", with base endpoint:" + this.options.baseEndPoint + ", ver.: " + this.version);
+            (0, BlueGreenState_1.startBlueGreenWatcher)(this.options.blueGreenWatchMs ?? 5000);
         });
     }
     addNetlog(data, req, created, time) {
@@ -478,11 +496,11 @@ class APIService extends BaseService_1.BaseService {
             time: time,
             request: {
                 endpoint: req?.endpoint,
-                headers: req?.headers,
+                headers: LogService_1.LogService.sanitizeDeep(req?.headers),
                 method: req?.method,
                 data: this.checkDataLength(req?.data),
-                params: req?.params,
-                interceptorResult: req?.interceptorResult
+                params: LogService_1.LogService.sanitizeDeep(req?.params),
+                interceptorResult: LogService_1.LogService.sanitizeDeep(req?.interceptorResult)
             },
             response: this.checkDataLength(data),
         };
@@ -600,7 +618,7 @@ class APIService extends BaseService_1.BaseService {
                     return v.slice(0, 255) + `...(${v.length})`;
                 return v;
             });
-            json = typeof s === "string" ? s : "";
+            json = typeof s === "string" ? LogService_1.LogService.sanitize(s) : "";
         }
         catch (e) {
             json = "[unserializable data]";

package/dist/apiServer/LogService.d.ts

@@ -63,8 +63,10 @@ export declare class LogService extends BaseService {
     leadZero(num: number): string;
     createText(data: any, level: LOG_LEVEL): string;
     private static readonly SANITIZERS;
+    private static readonly SENSITIVE_KEY_RE;
     static sanitize(text: string): string;
     private static readonly PAN_CANDIDATE_REGEX;
     private static isLuhnValid;
+    static sanitizeDeep(value: any, depth?: number): any;
     static maskPAN(text: string): string;
 }

package/dist/apiServer/LogService.js

@@ -265,7 +265,9 @@ class LogService extends BaseService_1.BaseService {
         [/;\d{13,19}=\d{4,}[^?]*\?/g, "<REDACTED TRACK2>"],
         [/("(?:password|passwd|pwd|secret|api[_-]?key|api[_-]?secret|client[_-]?secret|access[_-]?key|private[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|authorization|cookie|set[_-]?cookie|session[_-]?id|sess[_-]?id|sid|cvv2?|cvc2?|cvn|cav2?|cid|security[_-]?code|card[_-]?verification[_-]?(?:value|code)?|pin|pin[_-]?block|encrypted[_-]?pin|iso[_-]?9564|exp|expiry|expiration|expiration[_-]?date|exp[_-]?date|exp[_-]?month|exp[_-]?year|cardholder[_-]?name|holder[_-]?name|card[_-]?holder)"\s*:\s*)"[^"]*"/gi, '$1"<REDACTED>"'],
         [/("(?:cvv2?|cvc2?|pin|exp[_-]?month|exp[_-]?year|service[_-]?code)"\s*:\s*)(-?\d+)/gi, '$1"<REDACTED>"'],
+        [/([?&;](?:password|passwd|pwd|secret|token|access[_-]?token|refresh[_-]?token|id[_-]?token|api[_-]?key|apikey|auth|authorization|session|session[_-]?id|sid|cvv2?|cvc2?|pin|pan|signature|sig)=)[^&\s"'<>;]*/gi, "$1<REDACTED>"],
     ];
+    static SENSITIVE_KEY_RE = /^(?:authorization|proxy-authorization|cookie|set-cookie|x-api-key|api[_-]?key|apikey|password|passwd|pwd|secret|client[_-]?secret|access[_-]?key|private[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|session[_-]?id|sess[_-]?id|sid|cvv2?|cvc2?|cvn|cav2?|security[_-]?code|card[_-]?verification[_-]?(?:value|code)?|pin|pin[_-]?block|pan|card[_-]?number|exp|expiry|expiration|exp[_-]?date|exp[_-]?month|exp[_-]?year|cardholder[_-]?name|holder[_-]?name|card[_-]?holder)$/i;
     static sanitize(text) {
         if (!text || text.length < 3)
             return text;
@@ -295,6 +297,47 @@ class LogService extends BaseService_1.BaseService {
         }
         return sum % 10 === 0;
     }
+    static sanitizeDeep(value, depth = 0) {
+        if (depth > 8)
+            return "<DEPTH LIMIT>";
+        if (value === null || value === undefined)
+            return value;
+        const t = typeof value;
+        if (t === "string")
+            return LogService.sanitize(value);
+        if (t === "number" || t === "boolean")
+            return value;
+        if (t === "function" || t === "symbol")
+            return `[${t}]`;
+        if (t === "bigint")
+            return value.toString();
+        if (Buffer.isBuffer(value))
+            return `[Buffer ${value.length} bytes]`;
+        if (value instanceof Date)
+            return value.toISOString();
+        if (Array.isArray(value)) {
+            const capped = value.length > 200 ? value.slice(0, 200) : value;
+            const out = capped.map(v => LogService.sanitizeDeep(v, depth + 1));
+            if (value.length > capped.length)
+                out.push(`…(${value.length} items total)`);
+            return out;
+        }
+        if (t === "object") {
+            const out = {};
+            let n = 0;
+            for (const k of Object.keys(value)) {
+                if (++n > 200) {
+                    out["…"] = `(${Object.keys(value).length} keys total)`;
+                    break;
+                }
+                out[k] = LogService.SENSITIVE_KEY_RE.test(k)
+                    ? "<REDACTED>"
+                    : LogService.sanitizeDeep(value[k], depth + 1);
+            }
+            return out;
+        }
+        return String(value);
+    }
     static maskPAN(text) {
         if (!text || text.length < 13)
             return text;

package/dist/apiServer/deployment/BlueGreenState.d.ts

@@ -0,0 +1,31 @@
+import Signal from "badmfck-signal";
+export declare const BLUEGREEN_FILE = ".bluegreen.json";
+export type TSlot = "blue" | "green";
+export interface IBlueGreenState {
+    live: boolean | null;
+    bluegreen: boolean;
+    project: string | null;
+    slot: TSlot | null;
+    active: TSlot | null;
+    isActive: boolean | null;
+    lastDeployed: TSlot | null;
+    readyToSwitch: boolean | null;
+    checkedAt: number;
+    cached: boolean;
+    stale?: boolean;
+    error?: string;
+}
+export declare const S_BLUEGREEN_STATE_CHANGED: Signal<{
+    current: IBlueGreenState;
+    previous: IBlueGreenState | null;
+}>;
+export interface IBlueGreenStateOptions {
+    force?: boolean;
+    ttlMs?: number;
+    timeoutMs?: number;
+}
+export declare function onLiveChange(cb: (live: boolean, state: IBlueGreenState) => void): () => void;
+export declare function getBlueGreenStateSync(): IBlueGreenState | null;
+export declare function startBlueGreenWatcher(intervalMs?: number): void;
+export declare function stopBlueGreenWatcher(): void;
+export declare function getBlueGreenActiveState(opts?: IBlueGreenStateOptions): Promise<IBlueGreenState>;

package/dist/apiServer/deployment/BlueGreenState.js

@@ -0,0 +1,150 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S_BLUEGREEN_STATE_CHANGED = exports.BLUEGREEN_FILE = void 0;
+exports.onLiveChange = onLiveChange;
+exports.getBlueGreenStateSync = getBlueGreenStateSync;
+exports.startBlueGreenWatcher = startBlueGreenWatcher;
+exports.stopBlueGreenWatcher = stopBlueGreenWatcher;
+exports.getBlueGreenActiveState = getBlueGreenActiveState;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const badmfck_signal_1 = __importDefault(require("badmfck-signal"));
+exports.BLUEGREEN_FILE = ".bluegreen.json";
+exports.S_BLUEGREEN_STATE_CHANGED = new badmfck_signal_1.default();
+let cache = null;
+let inflight = null;
+let lastKnown = null;
+let watchTimer = null;
+function remember(fresh) {
+    const previous = lastKnown;
+    if (fresh.live === null && previous && previous.live !== null && fresh.bluegreen) {
+        lastKnown = { ...previous, checkedAt: fresh.checkedAt, stale: true, error: fresh.error };
+        return;
+    }
+    lastKnown = { ...fresh, cached: false, stale: false };
+    if (!previous || previous.live !== lastKnown.live || previous.isActive !== lastKnown.isActive
+        || previous.active !== lastKnown.active) {
+        try {
+            exports.S_BLUEGREEN_STATE_CHANGED.invoke({ current: lastKnown, previous });
+        }
+        catch { }
+    }
+}
+function onLiveChange(cb) {
+    let delivered = null;
+    const deliver = (s) => {
+        if (!s || s.live === null || s.live === delivered)
+            return;
+        delivered = s.live;
+        try {
+            cb(s.live, s);
+        }
+        catch { }
+    };
+    const id = exports.S_BLUEGREEN_STATE_CHANGED.subscribe(({ current }) => deliver(current));
+    deliver(lastKnown);
+    return () => { exports.S_BLUEGREEN_STATE_CHANGED.unsubscribe(id); };
+}
+function getBlueGreenStateSync() {
+    return lastKnown;
+}
+function startBlueGreenWatcher(intervalMs = 5000) {
+    if (watchTimer || intervalMs <= 0)
+        return;
+    const tick = async () => {
+        const s = await getBlueGreenActiveState({ force: true });
+        if (!s.bluegreen)
+            stopBlueGreenWatcher();
+    };
+    watchTimer = setInterval(() => { tick().catch(() => { }); }, intervalMs);
+    watchTimer.unref?.();
+    tick().catch(() => { });
+}
+function stopBlueGreenWatcher() {
+    if (watchTimer)
+        clearInterval(watchTimer);
+    watchTimer = null;
+}
+function findFile() {
+    const override = process.env.BLUEGREEN_FILE;
+    if (override)
+        return fs_1.default.existsSync(override) ? override : null;
+    const main = require.main?.filename ?? process.argv[1];
+    if (!main)
+        return null;
+    let dir = path_1.default.dirname(path_1.default.resolve(main));
+    for (let i = 0; i < 6; i++) {
+        const candidate = path_1.default.join(dir, exports.BLUEGREEN_FILE);
+        if (fs_1.default.existsSync(candidate))
+            return candidate;
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function readFile(file) {
+    try {
+        const j = JSON.parse(fs_1.default.readFileSync(file, "utf-8"));
+        if (j && typeof j.project === "string" && (j.slot === "blue" || j.slot === "green")
+            && typeof j.statusUrl === "string" && typeof j.token === "string")
+            return j;
+    }
+    catch { }
+    return null;
+}
+async function query(timeoutMs) {
+    const base = {
+        live: true, bluegreen: false, project: null, slot: null, active: null, isActive: null,
+        lastDeployed: null, readyToSwitch: null, checkedAt: Date.now(), cached: false,
+    };
+    const file = findFile();
+    if (!file)
+        return base;
+    const cfg = readFile(file);
+    if (!cfg)
+        return { ...base, live: null, bluegreen: true, error: `${exports.BLUEGREEN_FILE} at ${file} is unreadable or malformed` };
+    const known = { ...base, live: null, bluegreen: true, project: cfg.project, slot: cfg.slot };
+    try {
+        const res = await fetch(cfg.statusUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ name: cfg.project, token: cfg.token, slot: cfg.slot }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const body = await res.json().catch(() => null);
+        const d = body?.data;
+        if (!res.ok || body?.error || !d) {
+            const reason = body?.error?.message ?? `HTTP ${res.status}`;
+            return { ...known, error: `deployer rejected the status query: ${reason}` };
+        }
+        const slotOrNull = (v) => (v === "blue" || v === "green" ? v : null);
+        const active = slotOrNull(d.active);
+        return {
+            ...known,
+            live: active ? active === cfg.slot : null,
+            active,
+            lastDeployed: slotOrNull(d.lastDeployed),
+            readyToSwitch: typeof d.readyToSwitch === "boolean" ? d.readyToSwitch : null,
+            isActive: active ? active === cfg.slot : null,
+        };
+    }
+    catch (e) {
+        return { ...known, error: `deployer unreachable at ${cfg.statusUrl}: ${e?.message ?? e}` };
+    }
+}
+async function getBlueGreenActiveState(opts) {
+    const ttl = opts?.ttlMs ?? 10_000;
+    if (!opts?.force && cache && Date.now() - cache.at < ttl)
+        return { ...cache.value, cached: true };
+    if (inflight)
+        return inflight;
+    inflight = query(opts?.timeoutMs ?? 3000)
+        .then(value => { cache = { at: Date.now(), value }; remember(value); return value; })
+        .finally(() => { inflight = null; });
+    return inflight;
+}

package/dist/apiServer/deployment/ConfigService.d.ts

@@ -15,6 +15,8 @@ declare const _ProjectState: {
         readonly user: "";
         readonly at: 0;
     }];
+    readonly statusToken: "";
+    readonly $__statusToken_optional: true;
 };
 export type IProjectState = ValidationModel<typeof _ProjectState>;
 declare const _TConfig: {

package/dist/apiServer/deployment/ConfigService.js

@@ -58,6 +58,8 @@ const _ProjectState = {
             user: "",
             at: 0,
         }],
+    statusToken: "",
+    $__statusToken_optional: true,
 };
 const _TConfig = {
     name: "",