@tyhld/conductor 0.3.0 → 0.7.0

package/dist/realtime-parse.js

@@ -0,0 +1,116 @@
+/**
+ * @tyhld/conductor — ADR-066 耳の「読み取りと間合いの計算」だけを集めたモジュール（外部I/Oなし）。
+ *
+ * 耳の中で判断にあたるのは次の4つで、いずれも入力から結論が決まる純粋関数にしてある:
+ *   ① realtime-token の応答を読めるか（読めない応答で半端に張りに行かない）
+ *   ② 合図から宛先(site)だけを読む（★本文は読まない・使わない）
+ *   ③ いつトークンを取り直すか（失効の手前・下限と上限で挟む）
+ *   ④ 切れたとき何秒後に張り直すか（指数バックオフ）
+ * 実際の接続・通信は src/realtime.ts 側にある。ここを分けてあるのは、判断だけを単体テストで
+ * 固定できるようにするため（src/ear-routing.ts と同じ流儀）。
+ */
+/** 接続情報を問い合わせるときのタイムアウト(ms)。起動をハングさせないため短く切る。 */
+export const EAR_TOKEN_FETCH_TIMEOUT_MS = 10 * 1000;
+/** 合図が連続したときに取得APIを叩く最小間隔(ms)。束ねても取りこぼさない（本文はAPIから取るため）。 */
+export const EAR_NUDGE_MIN_GAP_MS = 1000;
+/** 失効の何ms手前でトークンを取り直すか。 */
+export const EAR_REFRESH_MARGIN_MS = 10 * 60 * 1000;
+/** 張り直し間隔の下限・上限、および expiresAt が読めないときの既定（9時間より十分手前）。 */
+export const EAR_REFRESH_MIN_MS = 60 * 1000;
+export const EAR_REFRESH_MAX_MS = 8 * 60 * 60 * 1000;
+export const EAR_REFRESH_FALLBACK_MS = 8 * 60 * 60 * 1000;
+/** 再接続の待ち（指数バックオフ）の初期値と上限。 */
+export const EAR_RETRY_BASE_MS = 5 * 1000;
+export const EAR_RETRY_MAX_MS = 5 * 60 * 1000;
+/** 購読設定が無い（unsupported）ときに問い直す間隔(ms)。中央の設定投入に自然に追従するため。 */
+export const EAR_UNSUPPORTED_RETRY_MS = 30 * 60 * 1000;
+/**
+ * この機で現場のrelayが1つも動いていないときに、もう一度見るまでの間隔(ms)。
+ *   既存APIの realtime-token は現場名を要るので、実在する現場が1つも無い間は張りに行かない
+ *   （在りもしない現場名を送って中央に弾かれるより、少し待って出そろってから張る方が素直）。
+ */
+export const EAR_NO_SITE_RETRY_MS = 60 * 1000;
+// ───────────────────────────────────────────────────────────────────────────
+// 純粋関数（I/Oなし＝単体テスト可能）
+// ───────────────────────────────────────────────────────────────────────────
+/** 空でない文字列ならその値、そうでなければ null。 */
+function str(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v : null;
+}
+/**
+ * realtime-token の応答(JSON)から接続一式を取り出す純粋関数。
+ *   - 購読に要るもの（token / supabaseUrl / supabaseAnonKey / subscribe.channel・schema・table・event）が
+ *     1つでも欠けたら 'unsupported'＝耳は生やさずポーリングのみで動く（ADR-066: エラーにしない）。
+ *   - 鍵の綴りは supabaseAnonKey / anonKey の両方を許容する（中央の応答が育っても壊れないように）。
+ */
+export function parseRealtimeConnection(data) {
+    if (data === null || typeof data !== 'object') {
+        return { kind: 'error', detail: '応答がJSONオブジェクトでない' };
+    }
+    const d = data;
+    const token = str(d.token);
+    const supabaseUrl = str(d.supabaseUrl);
+    const supabaseAnonKey = str(d.supabaseAnonKey) ?? str(d.anonKey);
+    const sub = d.subscribe;
+    if (token === null)
+        return { kind: 'error', detail: 'token が無い' };
+    if (sub === null || typeof sub !== 'object') {
+        return { kind: 'unsupported', detail: '応答に subscribe が無い' };
+    }
+    if (supabaseUrl === null || supabaseAnonKey === null) {
+        return { kind: 'unsupported', detail: '応答に接続先(URL/公開鍵)が無い' };
+    }
+    const s = sub;
+    const channel = str(s.channel);
+    const schema = str(s.schema);
+    const table = str(s.table);
+    const event = str(s.event);
+    if (channel === null || schema === null || table === null || event === null) {
+        return { kind: 'unsupported', detail: 'subscribe の項目が足りない' };
+    }
+    const filter = str(s.filter);
+    return {
+        kind: 'ok',
+        conn: {
+            token,
+            expiresAt: str(d.expiresAt),
+            supabaseUrl,
+            supabaseAnonKey,
+            subscribe: filter === null ? { channel, schema, table, event } : { channel, schema, table, event, filter },
+        },
+    };
+}
+/**
+ * 合図から「宛先の現場名」だけを読む純粋関数（★振り分けにのみ使う。本文は読まない）。
+ *   合図の行には本文・報告・トークンの列がそもそも存在しない（ADR-066 §3）ので、site を読んでも
+ *   秘密は流れない。読めなければ null＝「宛先不明」とし、呼び出し側は取りに行く側へ倒す
+ *   （余計に1回取得APIを叩くだけ＝ポーリング1周の前倒しと同じで無害）。
+ */
+export function readSignalSite(payload) {
+    if (payload === null || typeof payload !== 'object')
+        return null;
+    const rec = payload.new;
+    if (rec === null || typeof rec !== 'object')
+        return null;
+    return str(rec.site);
+}
+/**
+ * トークンを取り直すまでの待ち(ms)を決める純粋関数。
+ *   失効時刻の EAR_REFRESH_MARGIN_MS 手前を狙い、下限・上限で挟む。
+ *   expiresAt が読めない/過去なら既定値（下限まで詰める）へ倒す＝「切れたまま気づかない」を作らない。
+ */
+export function computeRefreshDelayMs(expiresAt, nowMs) {
+    const clamp = (ms) => Math.min(EAR_REFRESH_MAX_MS, Math.max(EAR_REFRESH_MIN_MS, ms));
+    if (expiresAt === null)
+        return clamp(EAR_REFRESH_FALLBACK_MS);
+    const at = Date.parse(expiresAt);
+    if (!Number.isFinite(at))
+        return clamp(EAR_REFRESH_FALLBACK_MS);
+    return clamp(at - nowMs - EAR_REFRESH_MARGIN_MS);
+}
+/** 再接続の待ち(ms)。試行回数に応じて 5s → 10s → 20s …と広げ、5分で頭打ちにする。 */
+export function computeRetryDelayMs(attempt) {
+    const n = attempt < 0 ? 0 : attempt;
+    const ms = EAR_RETRY_BASE_MS * 2 ** Math.min(n, 20);
+    return Math.min(EAR_RETRY_MAX_MS, ms);
+}

package/dist/realtime.js

@@ -0,0 +1,251 @@
+/**
+ * @tyhld/conductor — ADR-066「指示の着信合図」を受け取る耳（Supabase Realtime の購読そのもの）。
+ *
+ * 【何のためか】
+ *   これまで relay は 15秒ポーリングだけで指示を拾っていた。指示が積まれてから職人へ届くまで
+ *   最大15秒の空白があり、お客さまには「押したのに動かない」時間として見える。
+ *   中央(devlog-tracker)側は ConductorCommand への INSERT をトリガで ConductorSignal へ写し、
+ *   Supabase Realtime で配信するところまで完成している（便2a・本番反映済み）。
+ *   ここではその合図を受け取り、「ポーリング1周を前倒しする」きっかけだけを作る。
+ *
+ * 【設計の要（ADR-066 の確定事項。勝手に変えない）】
+ *   ・合図の本文は使わない。合図は「何か来た」の呼び鈴でしかなく、指示の中身は必ず既存の
+ *     取得API(GET /api/conductor/commands)から取り直す。＝真実は常に中央のAPIにある。
+ *   ・接続先(URL・公開鍵)も購読名も、必ず POST /api/conductor/realtime-token の応答から受け取る。
+ *     このリポに URL・鍵・チャンネル名を書き写さない（2箇所に同じ文字列があると、片方だけ直して
+ *     「繋がっているのに届かない」事故になる）。env も足さない。
+ *   ・購読は machine 単位（filter: machine=eq.<machine>）。宛先の振り分けは呼び出し側（src/ear.ts）の仕事。
+ *   ・トークンは9時間で失効する。失効の手前で取り直して張り直す。
+ *   ・切断・エラーは自動再接続。★15秒ポーリングは消さない。線が切れている間はポーリングが
+ *     そのまま肩代わりする（＝耳が全部死んでも従来どおり動く）。
+ *
+ * 【便2c: この接続を張るのは1台に1本だけ】
+ *   便2b では relay プロセスごとにこの耳を張っていたため、接続本数が「PC数 × 現場数」で増えた。
+ *   便2c で耳を独立常駐(src/ear.ts / conductor-ear.service)へ移し、この モジュールを呼ぶのは
+ *   その1プロセスだけにした。relay は Realtime を張らず、耳からのプロセス間の合図(src/nudge.ts)で
+ *   1周を前倒しするだけ。＝接続本数はソフト数ではなく【PC数】で決まる。
+ *
+ * 【依存の扱い】@supabase/supabase-js は動的 import で読む。顧客PCで git pull だけして
+ *   npm install を忘れた状態でも、耳が起動不能になっては困る（起動不能＝黙って加速だけ失う方が良い）。
+ *   読めなければ「耳なし＝各relayのポーリングのみ」で静かに動き続ける。
+ */
+import { describeTransport, resolveWebSocketTransport } from './websocket-transport.js';
+import { EAR_NO_SITE_RETRY_MS, EAR_NUDGE_MIN_GAP_MS, EAR_TOKEN_FETCH_TIMEOUT_MS, EAR_UNSUPPORTED_RETRY_MS, computeRefreshDelayMs, computeRetryDelayMs, parseRealtimeConnection, readSignalSite, } from './realtime-parse.js';
+// 読み取りと間合いの計算は src/realtime-parse.ts に分けてある（外部I/Oなし＝単体テスト可能）。
+// 従来どおり `./realtime.js` からも使えるよう、ここで通しておく。
+export * from './realtime-parse.js';
+/** ログ（耳の出来事だと分かるよう [ear] にする）。 */
+const now = () => new Date().toLocaleTimeString();
+const log = (msg) => console.log(`[ear] ${now()} ${msg}`);
+// ───────────────────────────────────────────────────────────────────────────
+// I/O
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * 接続情報を中央へ問い合わせる。POST /api/conductor/realtime-token（テナントトークン Bearer）。
+ *   body に site と machine を送ると、応答に接続先・公開鍵・購読設定が付く（machine を送らない
+ *   従来の呼び方では付かない＝中央側は後方互換）。
+ *
+ * ★site は既存APIの仕様上の必須項目。耳はPC単位なので「今このPCで動いている現場」から1つ選んで
+ *   添える（購読は machine 単位で、どの現場を添えても受け取る合図は同じ）。中央側の変更は要らない。
+ */
+export async function fetchRealtimeConnection(cfg, site) {
+    try {
+        const res = await fetch(`${cfg.url}/api/conductor/realtime-token`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${cfg.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ site, machine: cfg.machine }),
+            signal: AbortSignal.timeout(EAR_TOKEN_FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return { kind: 'error', detail: `HTTP ${res.status}` };
+        const data = await res.json().catch(() => null);
+        return parseRealtimeConnection(data);
+    }
+    catch (err) {
+        return { kind: 'error', detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** supabase-js の createClient を動的に読む。入っていなければ null（＝ポーリングのみで動く）。 */
+async function loadCreateClient() {
+    try {
+        const mod = (await import('@supabase/supabase-js'));
+        return typeof mod.createClient === 'function' ? mod.createClient : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 指示の着信合図を受け取る耳を1本張る（★このPCに1本だけ＝耳プロセスからのみ呼ぶ）。
+ *
+ * 呼び出し側は各relayのポーリングを止めないこと——耳が死んでいる間はポーリングが肩代わりする。
+ */
+export function startRealtimeEar(cfg, handlers) {
+    const { siteForToken, onSignal } = handlers;
+    let stopped = false;
+    let client = null;
+    let channel = null;
+    let retryTimer = null;
+    let refreshTimer = null;
+    let attempt = 0;
+    let lastNudgeAt = 0;
+    /** 直近に束ね判定をした宛先（宛先ごとに束ねるため）。 */
+    let lastNudgeSite = null;
+    /** 再接続の予約が二重に積まれないようにする（切断イベントは連続で飛んでくる）。 */
+    let reconnectArmed = false;
+    const clearTimers = () => {
+        if (retryTimer) {
+            clearTimeout(retryTimer);
+            retryTimer = null;
+        }
+        if (refreshTimer) {
+            clearTimeout(refreshTimer);
+            refreshTimer = null;
+        }
+    };
+    const teardown = () => {
+        try {
+            if (client && channel)
+                client.removeChannel(channel);
+        }
+        catch {
+            /* 片付けの失敗で耳の再生を止めない */
+        }
+        try {
+            client?.realtime?.disconnect?.();
+        }
+        catch {
+            /* 同上 */
+        }
+        channel = null;
+        client = null;
+    };
+    /** 一拍おいて張り直す。理由はログに残す（凝らない＝最悪はポーリングが拾う）。 */
+    const scheduleReconnect = (reason) => {
+        if (stopped || reconnectArmed)
+            return;
+        reconnectArmed = true;
+        teardown();
+        const delay = computeRetryDelayMs(attempt);
+        attempt += 1;
+        log(`${reason} → ${Math.round(delay / 1000)}秒後に張り直します（この間は各relayの15秒ポーリングが肩代わり）`);
+        clearTimers();
+        retryTimer = setTimeout(() => {
+            reconnectArmed = false;
+            void connect();
+        }, delay);
+    };
+    /** 失効の手前で張り直す（トークンは9時間で切れる）。 */
+    const scheduleRefresh = (expiresAt) => {
+        if (stopped)
+            return;
+        const delay = computeRefreshDelayMs(expiresAt, Date.now());
+        if (refreshTimer)
+            clearTimeout(refreshTimer);
+        refreshTimer = setTimeout(() => {
+            if (stopped)
+                return;
+            log('接続の期限が近いので張り直します');
+            teardown();
+            void connect();
+        }, delay);
+    };
+    const handleSignal = (payload) => {
+        // ★payload の中身は使わない。読むのは宛先(site)だけで、指示本文は受け手が取得APIから取り直す。
+        const signalSite = readSignalSite(payload);
+        const t = Date.now();
+        // 同じ宛先への連続した合図だけを束ねる（別の現場宛てが続いたときに取りこぼさないよう宛先ごとに見る）。
+        const key = signalSite ?? '';
+        if (key === lastNudgeSite && t - lastNudgeAt < EAR_NUDGE_MIN_GAP_MS)
+            return;
+        lastNudgeSite = key;
+        lastNudgeAt = t;
+        onSignal(signalSite);
+    };
+    const connect = async () => {
+        if (stopped)
+            return;
+        const createClient = await loadCreateClient();
+        if (createClient === null) {
+            log('@supabase/supabase-js が読めないため耳は張りません（各relayの15秒ポーリングでこれまでどおり動きます）');
+            return; // 依存は実行中に生えないので再試行しない。
+        }
+        // ★どの Node(18/20/22) でも耳が張れるようにする（実機 Node 20 の「native WebSocket not found」根治）。
+        //   標準の WebSocket が無い機では同梱の ws を supabase-js の transport へ渡す。
+        //   どちらも用意できなければ耳は張らない——が、プロセスは落とさない（ポーリングが肩代わりする）。
+        const transport = await resolveWebSocketTransport();
+        if (transport === null) {
+            log('この機には標準のWebSocketが無く、同梱のWebSocket部品(ws)も読めないため耳は張りません' +
+                '（npm install で解消します。それまでも各relayの15秒ポーリングでこれまでどおり動きます）');
+            return; // 部品は実行中に生えないので再試行しない。
+        }
+        const site = siteForToken();
+        if (site === null) {
+            log(`この機でまだ現場のrelayが1つも動いていないため、耳は待機します（${Math.round(EAR_NO_SITE_RETRY_MS / 1000)}秒後にもう一度見ます）`);
+            clearTimers();
+            retryTimer = setTimeout(() => void connect(), EAR_NO_SITE_RETRY_MS);
+            return;
+        }
+        const result = await fetchRealtimeConnection(cfg, site);
+        if (result.kind === 'unsupported') {
+            log(`中央から購読設定が返らないため耳は張りません（${result.detail}）。` +
+                `各relayの15秒ポーリングで動き続け、${Math.round(EAR_UNSUPPORTED_RETRY_MS / 60000)}分後にもう一度問い合わせます`);
+            clearTimers();
+            retryTimer = setTimeout(() => void connect(), EAR_UNSUPPORTED_RETRY_MS);
+            return;
+        }
+        if (result.kind === 'error') {
+            scheduleReconnect(`接続情報を取得できません（${result.detail}）`);
+            return;
+        }
+        const conn = result.conn;
+        try {
+            client = createClient(conn.supabaseUrl, conn.supabaseAnonKey, {
+                auth: { persistSession: false, autoRefreshToken: false },
+                // transport を明示して渡す＝supabase-js が自前で標準WebSocketを探して例外を投げる道を通らせない。
+                realtime: { transport: transport.ctor },
+            });
+            client.realtime?.setAuth?.(conn.token);
+            const spec = conn.subscribe;
+            const filterOpt = {
+                event: spec.event,
+                schema: spec.schema,
+                table: spec.table,
+            };
+            if (spec.filter !== undefined)
+                filterOpt.filter = spec.filter;
+            channel = client
+                .channel(spec.channel)
+                .on('postgres_changes', filterOpt, handleSignal)
+                .subscribe((status, err) => {
+                if (stopped)
+                    return;
+                if (status === 'SUBSCRIBED') {
+                    attempt = 0;
+                    reconnectArmed = false;
+                    log(`合図の受け取りを開始しました（machine=${cfg.machine} この機に1本 / ${describeTransport(transport)}）`);
+                    scheduleRefresh(conn.expiresAt);
+                    return;
+                }
+                if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT' || status === 'CLOSED') {
+                    const detail = err instanceof Error ? `: ${err.message}` : '';
+                    scheduleReconnect(`合図の線が切れました（${status}${detail}）`);
+                }
+            });
+        }
+        catch (err) {
+            scheduleReconnect(`購読の開始に失敗（${err instanceof Error ? err.message : String(err)}）`);
+        }
+    };
+    void connect();
+    return {
+        stop: () => {
+            stopped = true;
+            clearTimers();
+            teardown();
+        },
+    };
+}

package/dist/relay-runner.js

@@ -0,0 +1,65 @@
+/**
+ * @tyhld/conductor — relay の回し役（ポーリング＋合図の前倒しを1つの流れにまとめる）。
+ *
+ * 【なぜ切り出すか】ADR-066 便2b で relay の回り方に「合図(Realtime)で1周を前倒しする」が加わった。
+ *   ここは一見単純だが、間違えると静かに壊れる場所が2つある:
+ *     ① 予約を消さずに走ると、走行後に積む予約と元の予約が二重になり、ポーリングが倍・4倍と増える。
+ *        （中央への問い合わせ回数＝Vercel実行回数がじわじわ増える。誰も気づけない類の劣化。）
+ *     ② tick の走行中に来た合図を捨てると、その tick は合図より前の状態を見て終わっているかも
+ *        しれないので、指示が15秒待たされる（＝耳を付けた意味が消える）。
+ *   どちらもタイマー絡みで再現が面倒なので、cli.ts に直書きせず単体テストできる形にする。
+ *
+ * 【約束】
+ *   - 同時に走る tick は1つだけ（走行中の run() は「終わったらもう1周」の予約として畳む）。
+ *   - 予約中のタイマーは常に1本だけ（走り出す前に必ず消す）。
+ *   - tick が投げた例外でループを止めない（1回の失敗で配達も承認も止まってはいけない）。
+ *   - stop() 後は新しい tick を始めない・新しい予約も積まない。
+ */
+export function createRelayRunner(args) {
+    const { tick, nextDelayMs, onError } = args;
+    let timer = null;
+    let busy = false;
+    let nudged = false;
+    let stopped = false;
+    const clearTimer = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    };
+    const run = async () => {
+        if (stopped)
+            return;
+        if (busy) {
+            nudged = true; // 走行中に来た合図。今の tick が終わったらもう1周して取りに行く。
+            return;
+        }
+        busy = true;
+        clearTimer(); // ★予約を残したまま走ると、走行後の予約と二重になりポーリングが倍速化する。
+        try {
+            do {
+                nudged = false;
+                try {
+                    await tick();
+                }
+                catch (err) {
+                    onError?.(err);
+                }
+            } while (nudged && !stopped);
+        }
+        finally {
+            busy = false;
+        }
+        if (stopped)
+            return;
+        clearTimer();
+        timer = setTimeout(() => void run(), nextDelayMs());
+    };
+    return {
+        run,
+        stop: () => {
+            stopped = true;
+            clearTimer();
+        },
+    };
+}