pixivflow 2.10.31 → 2.12.0

package/dist/scheduler/MultiScheduleManager.js

@@ -4,11 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MultiScheduleManager = void 0;
+exports.occurrenceToSlotContext = occurrenceToSlotContext;
 const node_fs_1 = require("node:fs");
 const cron_parser_1 = __importDefault(require("cron-parser"));
 const logger_1 = require("../logger");
 const Scheduler_1 = require("./Scheduler");
 const schedules_1 = require("./schedules");
+const OccurrenceResolver_1 = require("./OccurrenceResolver");
 class SerialJobAdmission {
     queueLimit;
     active = false;
@@ -92,6 +94,13 @@ class MultiScheduleManager {
     catchUpMissedRuns(config) {
         if (!this.options.database)
             return;
+        // External mode (Fly autosleep): a stopped machine is the normal saving
+        // state, not an outage — never self-trigger historical runs on cold start.
+        if (this.isExternalMode(config))
+            return;
+        // Opt-out for internal hosts that do not want startup catch-up.
+        if (config.schedulerRuntime?.catchUpMissedRuns === false)
+            return;
         const now = new Date();
         for (const plan of (0, schedules_1.resolveSchedules)(config)) {
             if (!plan.enabled)
@@ -105,13 +114,17 @@ class MultiScheduleManager {
             try {
                 const interval = cron_parser_1.default.parseExpression(plan.cron, {
                     currentDate: lastEnd,
-                    tz: plan.timezone ?? 'Asia/Shanghai',
+                    tz: plan.timezone ?? config.scheduler?.timezone,
                 });
                 const nextExpected = interval.next().toDate();
                 if (nextExpected.getTime() <= now.getTime()) {
+                    // Resolve the missed canonical occurrence so catch-up opens the SAME
+                    // slot a timely cron tick would have (bounded: only the one missed
+                    // fire, never an unbounded historical replay).
+                    const missed = (0, OccurrenceResolver_1.resolveOccurrence)({ schedule: plan, at: now, triggerSource: 'catchup' });
                     logger_1.logger.warn(`Schedule ${plan.id}: cron fire was missed while the daemon was down ` +
                         `(next expected after last run ${lastEnd.toISOString()} at ${nextExpected.toISOString()}); running catch-up now`);
-                    scheduler.runNow();
+                    scheduler.runNow({ triggerSource: 'catchup', slot: occurrenceToSlotContext(missed) });
                 }
             }
             catch (error) {
@@ -150,6 +163,7 @@ class MultiScheduleManager {
         const plans = (0, schedules_1.resolveSchedules)(config);
         const enabledPlans = plans.filter((plan) => plan.enabled);
         const queueLimit = config.schedulerRuntime?.queueLimit ?? Math.max(enabledPlans.length, 1);
+        const registerCron = !this.isExternalMode(config);
         // loadConfig performs full validation. Stop the previous cron table only
         // after every new definition is available, then publish one snapshot.
         for (const scheduler of this.schedulers.values())
@@ -164,10 +178,11 @@ class MultiScheduleManager {
             // wedged run cannot hold the shared admission queue forever.
             const schedulerConfig = plan.timeout !== undefined ? plan : { ...plan, timeout: Scheduler_1.DEFAULT_SCHEDULE_TIMEOUT_MS };
             const scheduler = new Scheduler_1.Scheduler(schedulerConfig, this.options.database, this.options.telemetry, plan.id, this.admission, (failure) => this.options.onFailure?.(config, plan, failure));
-            scheduler.start(async () => {
+            scheduler[registerCron ? 'start' : 'init'](async (options) => {
                 // The closure keeps the exact validated snapshot for an in-flight run.
-                // Later runs are attached to the replacement cron table.
-                await this.options.execute(config, plan);
+                // Cron fires pass no options (runJob resolves the occurrence for now);
+                // catch-up and HTTP triggers pass a pre-resolved occurrence / source.
+                await this.options.execute(config, plan, options ?? { triggerSource: 'cron' });
             });
             this.schedulers.set(plan.id, scheduler);
         }
@@ -219,6 +234,27 @@ class MultiScheduleManager {
             scheduler.stop();
         this.schedulers.clear();
     }
+    /** External scheduler mode: runs are HTTP-triggered, never by internal cron. */
+    isExternalMode(config = this.activeConfig) {
+        return config.schedulerRuntime?.mode === 'external';
+    }
+    /**
+     * Trigger one schedule immediately (external HTTP trigger / run-once). Returns
+     * false if the schedule id is unknown. Honors Scheduler's running/pending and
+     * serial-admission guards, so duplicate triggers never double-run. The trigger
+     * adapter pre-resolves the canonical occurrence and passes it as `options.slot`
+     * with `triggerSource: 'http'`; admission/ledger idempotency are the safety net.
+     */
+    triggerSchedule(scheduleId, options) {
+        const scheduler = this.schedulers.get(scheduleId);
+        if (!scheduler)
+            return false;
+        return scheduler.runNow(options);
+    }
+    /** Enabled schedule ids in the active snapshot (for the trigger API / status). */
+    scheduleIds() {
+        return [...this.schedulers.keys()];
+    }
     getStatus() {
         return {
             ok: true,
@@ -228,4 +264,18 @@ class MultiScheduleManager {
     }
 }
 exports.MultiScheduleManager = MultiScheduleManager;
+/** Map a resolved canonical occurrence to the durable SlotContext runJob uses. */
+function occurrenceToSlotContext(o) {
+    return {
+        slotId: o.slotId,
+        scheduleId: o.scheduleId,
+        occurrenceAt: o.occurrenceAt.getTime(),
+        occurrenceDate: o.occurrenceDate,
+        occurrenceLabel: o.occurrenceLabel,
+        timezone: o.timezone,
+        triggerSource: o.triggerSource,
+        slotName: o.occurrenceLabel,
+        slotDate: o.occurrenceDate,
+    };
+}
 //# sourceMappingURL=MultiScheduleManager.js.map

package/dist/scheduler/MultiScheduleManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"MultiScheduleManager.js","sourceRoot":"","sources":["../../src/scheduler/MultiScheduleManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"MultiScheduleManager.js","sourceRoot":"","sources":["../../src/scheduler/MultiScheduleManager.ts"],"names":[],"mappings":"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"}

package/dist/scheduler/OccurrenceResolver.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Canonical Schedule Occurrence resolution.
+ *
+ * A Slot is "one durable execution occurrence of a configured Schedule" — it is
+ * NOT a morning/evening row. Identity derives from (schedule definition, the
+ * schedule's own cron + timezone, and the trigger moment): every trigger source
+ * (internal cron tick, authenticated HTTP trigger, bounded internal catch-up)
+ * resolves the SAME canonical scheduled time for a given wall-clock instant, so
+ * duplicate/concurrent/retry triggers converge on one Slot.
+ *
+ * Pure + dependency-light (cron-parser is already a production dependency).
+ * This module is the ONLY place that computes occurrence identity / due-window.
+ * Adapters (cron/http/cli) must never hand-roll slot ids or dates.
+ */
+import { ScheduleConfig } from '../config';
+import type { SlotContext } from './SlotCoordinator';
+export type TriggerSource = 'cron' | 'http' | 'manual' | 'catchup';
+/**
+ * Options for running a schedule, accepted by every trigger adapter (internal
+ * cron, authenticated HTTP, manual CLI) so they all funnel through the one
+ * ScheduleExecutionService. This is the cross-layer contract between the
+ * scheduler manager / trigger HTTP server and the runtime's runJob.
+ */
+export interface ScheduleRunOptions {
+    /** Run only this target id (explicit operator replacement / "重抓"). */
+    onlyTarget?: string;
+    /** Why this run was started. Defaults to 'cron' for scheduled runs. */
+    triggerSource?: TriggerSource;
+    /**
+     * Ad-hoc/manual execution (run-once / refetch): runs the download plan but
+     * never opens a scheduled Slot, so it can neither mark a scheduled occurrence
+     * complete nor be resumed as one. Explicit replacement, not automatic retry.
+     */
+    adhoc?: boolean;
+    /**
+     * Pre-resolved occurrence for a scheduled run (cron/http/catchup). When
+     * omitted and `adhoc` is false, runJob resolves the canonical occurrence for
+     * now via the schedule's own cron + timezone.
+     */
+    slot?: SlotContext;
+}
+export interface OccurrenceInput {
+    schedule: ScheduleConfig;
+    /** Wall-clock instant of the trigger. Defaults to now. */
+    at?: Date;
+    /** Why this execution was started (recorded for observability only). */
+    triggerSource: TriggerSource;
+}
+export interface ResolvedOccurrence {
+    /**
+     * Durable, schedule-scoped identity: `<scheduleId>@<occurrenceAt ISO in tz>`.
+     * occurrenceAt is the canonical scheduled fire time (minute precision), so a
+     * 10:10 watchdog and a 10:00 cron both map to the 10:00 occurrence.
+     */
+    slotId: string;
+    scheduleId: string;
+    /** Canonical scheduled fire time (UTC Date). */
+    occurrenceAt: Date;
+    /** ISO-8601 with the schedule's tz offset, e.g. 2026-09-08T10:00:00+08:00. */
+    occurrenceAtIso: string;
+    /** Schedule date (YYYY-MM-DD) in the schedule timezone — for display only. */
+    occurrenceDate: string;
+    /** Human label of the scheduled time-of-day in tz (e.g. "10:00"). */
+    occurrenceLabel: string;
+    timezone: string;
+    triggerSource: TriggerSource;
+    /** Schedule display name (provenance only; never parsed). */
+    scheduleName: string;
+}
+export interface OccurrenceWindow {
+    ok: boolean;
+    /** 425 = not due yet, 410 = expired (outside grace). */
+    status?: 425 | 410;
+    error?: string;
+}
+/** Resolve the schedule's configured timezone (never the server's local tz). */
+export declare function scheduleTimezone(schedule: ScheduleConfig | undefined, fallback?: string): string;
+/**
+ * Return the most recent scheduled fire time of `cron` at or before `at` in
+ * `tz`. This is the canonical occurrence for a trigger arriving at `at`: late
+ * triggers (watchdog/retry/wake delay) resolve to the fire they belong to.
+ */
+export declare function resolveOccurrence(input: OccurrenceInput): ResolvedOccurrence;
+/**
+ * Validate that a trigger at `at` may run `occurrence`: it is runnable from a
+ * small lead before its scheduled time until `graceMinutes` after. Outside that
+ * window external clocks must not execute (no historical back-fill).
+ */
+export declare function checkOccurrenceWindow(occurrence: ResolvedOccurrence, at: Date, graceMinutes: number, leadMinutes?: number): OccurrenceWindow;
+//# sourceMappingURL=OccurrenceResolver.d.ts.map

package/dist/scheduler/OccurrenceResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OccurrenceResolver.d.ts","sourceRoot":"","sources":["../../src/scheduler/OccurrenceResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,cAAc,CAAC;IACzB,0DAA0D;IAC1D,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,wEAAwE;IACxE,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,YAAY,EAAE,IAAI,CAAC;IACnB,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;IAC7B,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,wDAAwD;IACxD,MAAM,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhG;AAwBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,kBAAkB,CAkD5E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,kBAAkB,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,SAAK,GAAG,gBAAgB,CAoBxI"}

package/dist/scheduler/OccurrenceResolver.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Canonical Schedule Occurrence resolution.
+ *
+ * A Slot is "one durable execution occurrence of a configured Schedule" — it is
+ * NOT a morning/evening row. Identity derives from (schedule definition, the
+ * schedule's own cron + timezone, and the trigger moment): every trigger source
+ * (internal cron tick, authenticated HTTP trigger, bounded internal catch-up)
+ * resolves the SAME canonical scheduled time for a given wall-clock instant, so
+ * duplicate/concurrent/retry triggers converge on one Slot.
+ *
+ * Pure + dependency-light (cron-parser is already a production dependency).
+ * This module is the ONLY place that computes occurrence identity / due-window.
+ * Adapters (cron/http/cli) must never hand-roll slot ids or dates.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scheduleTimezone = scheduleTimezone;
+exports.resolveOccurrence = resolveOccurrence;
+exports.checkOccurrenceWindow = checkOccurrenceWindow;
+const cron_parser_1 = __importDefault(require("cron-parser"));
+const DEFAULT_TZ = 'UTC';
+/** Resolve the schedule's configured timezone (never the server's local tz). */
+function scheduleTimezone(schedule, fallback) {
+    return schedule?.timezone?.trim() || fallback?.trim() || DEFAULT_TZ;
+}
+function partsInTz(date, tz) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone: tz,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(date);
+    const get = (t) => parts.find((p) => p.type === t)?.value ?? '';
+    return { y: get('year'), m: get('month'), d: get('day') };
+}
+function hhmmInTz(date, tz) {
+    const parts = new Intl.DateTimeFormat('en-GB', {
+        timeZone: tz,
+        hour: '2-digit',
+        minute: '2-digit',
+        hour12: false,
+    }).formatToParts(date);
+    const get = (t) => parts.find((p) => p.type === t)?.value ?? '00';
+    return `${get('hour')}:${get('minute')}`;
+}
+/**
+ * Return the most recent scheduled fire time of `cron` at or before `at` in
+ * `tz`. This is the canonical occurrence for a trigger arriving at `at`: late
+ * triggers (watchdog/retry/wake delay) resolve to the fire they belong to.
+ */
+function resolveOccurrence(input) {
+    const { schedule, at = new Date(), triggerSource } = input;
+    const tz = scheduleTimezone(schedule);
+    const cronExpr = schedule.cron;
+    if (!cronExpr) {
+        throw new Error(`schedule ${schedule.id} has no cron expression; cannot resolve occurrence`);
+    }
+    // A trigger belongs to the occurrence whose window contains the trigger
+    // instant: the last fire at/before `at`, OR — when `at` is just before a fire
+    // (clock fired a hair early / a small lead) — that upcoming fire. Resolving to
+    // "yesterday's fire" for an on-time tick is what a naive prev() would do
+    // (cron-parser is exclusive of the anchor), so peek both sides and pick the
+    // occurrence whose lead/grace window actually contains `at`.
+    // cron-parser treats the anchor instant as exclusive: prev() exactly AT a
+    // fire time returns the PREVIOUS fire. Nudge the anchor a minute forward (a
+    // schedule is minute-granular) so an on-time tick resolves to its own fire,
+    // then pick prev vs the upcoming fire by window.
+    const anchor = new Date(at.getTime() + 60_000);
+    const interval = cron_parser_1.default.parseExpression(cronExpr, { currentDate: anchor, tz, iterator: false });
+    const prev = interval.prev().toDate();
+    const next = cron_parser_1.default
+        .parseExpression(cronExpr, { currentDate: at, tz, iterator: false })
+        .next()
+        .toDate();
+    // Default to the most recent fire; prefer the upcoming one only when `at` is
+    // within its lead window (a clock that fired a hair early). Lead is
+    // resolver-internal and small (15 min).
+    const LEAD_MS = 15 * 60_000;
+    const fire = next.getTime() - at.getTime() <= LEAD_MS && next.getTime() >= at.getTime() ? next : prev;
+    const { y, m, d } = partsInTz(fire, tz);
+    const occurrenceDate = `${y}-${m}-${d}`;
+    const occurrenceLabel = hhmmInTz(fire, tz);
+    // Stable, filesystem/URL-safe id: minute precision in the tz wall clock.
+    const occurrenceStamp = `${occurrenceDate}T${occurrenceLabel.replace(':', '')}`;
+    const slotId = `${schedule.id}@${occurrenceStamp}`;
+    return {
+        slotId,
+        scheduleId: schedule.id,
+        occurrenceAt: fire,
+        occurrenceAtIso: fire.toISOString(),
+        occurrenceDate,
+        occurrenceLabel,
+        timezone: tz,
+        triggerSource,
+        scheduleName: schedule.name?.trim() || schedule.id,
+    };
+}
+/**
+ * Validate that a trigger at `at` may run `occurrence`: it is runnable from a
+ * small lead before its scheduled time until `graceMinutes` after. Outside that
+ * window external clocks must not execute (no historical back-fill).
+ */
+function checkOccurrenceWindow(occurrence, at, graceMinutes, leadMinutes = 15) {
+    const sched = occurrence.occurrenceAt.getTime();
+    const leadMs = leadMinutes * 60_000;
+    const graceMs = graceMinutes * 60_000;
+    const now = at.getTime();
+    if (now < sched - leadMs) {
+        return {
+            ok: false,
+            status: 425,
+            error: `schedule ${occurrence.scheduleId} occurrence ${occurrence.occurrenceAtIso} is not due yet`,
+        };
+    }
+    if (now > sched + graceMs) {
+        return {
+            ok: false,
+            status: 410,
+            error: `schedule ${occurrence.scheduleId} occurrence ${occurrence.occurrenceAtIso} has expired (grace ${graceMinutes}m)`,
+        };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=OccurrenceResolver.js.map

package/dist/scheduler/OccurrenceResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OccurrenceResolver.js","sourceRoot":"","sources":["../../src/scheduler/OccurrenceResolver.ts"],"names":[],"mappings":"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"}

package/dist/scheduler/ScheduleTriggerServer.d.ts

@@ -0,0 +1,60 @@
+import { SlotContext } from './SlotCoordinator';
+import { TriggerSource } from './OccurrenceResolver';
+/**
+ * Authenticated HTTP schedule trigger.
+ *
+ * A dumb external clock (Cloudflare cron worker, cron-job.org, GitHub Actions)
+ * POSTs a schedule id; this server wakes with the machine, verifies a bearer
+ * token, resolves the canonical occurrence from the schedule's OWN cron +
+ * timezone (never a client-supplied date), and runs that schedule synchronously
+ * so the open HTTP request keeps the machine active for the whole run — the
+ * request itself is the activity lease (no background fire-and-forget that lets
+ * a scale-to-zero host stop mid-run). All business state lives in the Slot
+ * ledger; the handler only authenticates, validates, resolves and delegates. It
+ * never queries Pixiv, loops targets, or touches the Slot DB itself.
+ *
+ * Mounting is independent of `schedulerRuntime.mode`: external mode mounts it as
+ * the primary clock; always-on/internal mode may also mount it for manual ops.
+ */
+export interface TriggerRunResult {
+    scheduleId: string;
+    slotId: string;
+    status: string;
+    alreadyCompleted?: boolean;
+    cells?: Array<{
+        targetId: string;
+        status: string;
+        workId: string | null;
+        error?: string | null;
+    }>;
+}
+export interface TriggerHandlers {
+    /** Enabled schedule ids (for 404 on unknown / GET listing). */
+    listSchedules(): string[];
+    /**
+     * Resolve the canonical occurrence for a trigger to `scheduleId` at `at`.
+     * Returns a durable SlotContext or an HTTP error ({ status, error }).
+     */
+    resolve(scheduleId: string, source: TriggerSource, at: Date, label?: string): {
+        context: SlotContext;
+    } | {
+        error: string;
+        status: number;
+    };
+    /** Run the schedule for a resolved occurrence; idempotent. */
+    run(scheduleId: string, context: SlotContext): Promise<TriggerRunResult>;
+    /** Read-only snapshot of a schedule's current occurrence (for GET). */
+    status(scheduleId: string): unknown;
+}
+export declare class ScheduleTriggerServer {
+    private readonly token;
+    private readonly handlers;
+    private server;
+    constructor(token: string | undefined, handlers: TriggerHandlers);
+    /** Token from config or SCHEDULER_TRIGGER_TOKEN env; empty => fail closed. */
+    static resolveToken(configured?: string): string | undefined;
+    start(host: string, port: number): void;
+    private auth;
+    stop(): void;
+}
+//# sourceMappingURL=ScheduleTriggerServer.d.ts.map

package/dist/scheduler/ScheduleTriggerServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleTriggerServer.d.ts","sourceRoot":"","sources":["../../src/scheduler/ScheduleTriggerServer.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CACnG;AAED,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,aAAa,IAAI,MAAM,EAAE,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,GACvE;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,GACxB;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,8DAA8D;IAC9D,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACzE,uEAAuE;IACvE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CACrC;AAED,qBAAa,qBAAqB;IAI9B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ3B,OAAO,CAAC,MAAM,CAAuB;gBAGlB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,EAAE,eAAe;IAG5C,8EAA8E;IAC9E,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAuDvC,OAAO,CAAC,IAAI,CAsBV;IAEF,IAAI,IAAI,IAAI;CAIb"}

package/dist/scheduler/ScheduleTriggerServer.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScheduleTriggerServer = void 0;
+const express_1 = __importDefault(require("express"));
+const node_crypto_1 = require("node:crypto");
+const logger_1 = require("../logger");
+class ScheduleTriggerServer {
+    token;
+    handlers;
+    server = null;
+    constructor(token, handlers) {
+        this.token = token;
+        this.handlers = handlers;
+    }
+    /** Token from config or SCHEDULER_TRIGGER_TOKEN env; empty => fail closed. */
+    static resolveToken(configured) {
+        return (configured ?? process.env.SCHEDULER_TRIGGER_TOKEN ?? '').trim() || undefined;
+    }
+    start(host, port) {
+        const app = (0, express_1.default)();
+        app.use(express_1.default.json());
+        app.get('/health', (_req, res) => {
+            res.json({ status: 'ok', service: 'pixivflow-scheduler-trigger' });
+        });
+        // Read-only: list enabled schedules + their current occurrence status.
+        app.get('/internal/schedules', this.auth, (_req, res) => {
+            const schedules = this.handlers.listSchedules().map((id) => this.handlers.status(id));
+            res.json({ schedules });
+        });
+        // Trigger one schedule by id. The server resolves the occurrence from the
+        // schedule cron; the body carries no date and cannot back-fill history.
+        app.post('/internal/schedules/:scheduleId/run', this.auth, async (req, res) => {
+            try {
+                const scheduleId = req.params.scheduleId;
+                if (!this.handlers.listSchedules().includes(scheduleId)) {
+                    res.status(404).json({ status: 'error', error: `unknown schedule: ${scheduleId}` });
+                    return;
+                }
+                // Optional human label for provenance (e.g. a deploy-layer "今日早班").
+                // Bounded; never parsed; identity always derives from the cron occurrence.
+                const label = typeof req.body?.label === 'string' ? req.body.label.slice(0, 80) : undefined;
+                const resolved = this.handlers.resolve(scheduleId, 'http', new Date(), label);
+                if (!('context' in resolved)) {
+                    res.status(resolved.status).json({ status: 'error', error: resolved.error });
+                    return;
+                }
+                const result = await this.handlers.run(scheduleId, resolved.context);
+                // alreadyCompleted => 200 with a clear note; real run => 200 completed.
+                res.status(result.alreadyCompleted ? 200 : 200).json({
+                    status: result.status === 'failed' ? 'failed' : 'ok',
+                    schedule: result,
+                    note: result.alreadyCompleted ? 'already_completed' : 'completed',
+                });
+            }
+            catch (error) {
+                logger_1.logger.error('Schedule trigger failed', { error: error instanceof Error ? error.message : String(error) });
+                // The slot ledger resumes on the next trigger; a 500 tells the clock to
+                // retry safely (idempotent — the same occurrence/ slot is reused).
+                res.status(500).json({ status: 'error', error: 'schedule run failed; the occurrence will resume on the next trigger' });
+            }
+        });
+        this.server = app.listen(port, host, () => {
+            logger_1.logger.info('Schedule trigger server listening', { host, port, auth: this.token ? 'bearer' : 'DISABLED (no token)' });
+        });
+    }
+    auth = (req, res, next) => {
+        if (!this.token) {
+            // Fail closed: never allow an unauthenticated trigger in production.
+            res.status(503).json({ status: 'error', error: 'trigger disabled: SCHEDULER_TRIGGER_TOKEN not configured' });
+            return;
+        }
+        const header = req.headers.authorization ?? '';
+        const presented = header.startsWith('Bearer ') ? header.slice(7).trim() : '';
+        const expected = this.token;
+        let ok = presented.length === expected.length;
+        if (ok) {
+            try {
+                ok = (0, node_crypto_1.timingSafeEqual)(Buffer.from(presented), Buffer.from(expected));
+            }
+            catch {
+                ok = false;
+            }
+        }
+        if (!ok) {
+            res.status(401).json({ status: 'error', error: 'unauthorized' });
+            return;
+        }
+        next();
+    };
+    stop() {
+        this.server?.close();
+        this.server = null;
+    }
+}
+exports.ScheduleTriggerServer = ScheduleTriggerServer;
+//# sourceMappingURL=ScheduleTriggerServer.js.map

package/dist/scheduler/ScheduleTriggerServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleTriggerServer.js","sourceRoot":"","sources":["../../src/scheduler/ScheduleTriggerServer.ts"],"names":[],"mappings":"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"}

package/dist/scheduler/Scheduler.d.ts

@@ -1,5 +1,6 @@
 import { SchedulerConfig } from '../config';
 import { Database } from '../storage/Database';
+import { ScheduleRunOptions } from './OccurrenceResolver';
 /**
  * Watchdog fallback: a schedule without an explicit `timeout` still gets this
  * cap so a wedged download run cannot occupy the scheduler queue forever.
@@ -49,12 +50,22 @@ export declare class Scheduler {
     private stopped;
     private pending;
     constructor(config: SchedulerConfig, database?: Database | undefined, telemetry?: JobTelemetry | undefined, scheduleId?: string, admission?: JobAdmissionController | undefined, onFailure?: ((failure: JobFailure) => Promise<void> | void) | undefined);
-    start(job: () => Promise<void>): void;
+    start(job: (options?: ScheduleRunOptions) => Promise<void>): void;
     /**
-     * Trigger one execution immediately (e.g. catch-up for a missed cron fire).
-     * Honors the same guards as a cron firing; no-op if already running.
+     * Arm the scheduler for external/manual triggers (runNow) WITHOUT registering
+     * a cron task. Used in `external` scheduler mode where an authenticated HTTP
+     * trigger — not the in-process clock — fires runs.
      */
-    runNow(): void;
+    init(job: (options?: ScheduleRunOptions) => Promise<void>): void;
+    private arm;
+    /**
+     * Trigger one execution immediately (external HTTP trigger / catch-up /
+     * run-once). Honors the same guards as a cron firing. Returns false when the
+     * run is not admitted (already running/pending, stopped, maxed) so callers
+     * can report idempotent "already in progress" instead of assuming a start.
+     * Fire-and-forget: the returned boolean only reports admission.
+     */
+    runNow(triggerOptions?: ScheduleRunOptions): boolean;
     private executeJob;
     /**
      * Execute the job. Item counting happens via JobTelemetry in executeJob,

package/dist/scheduler/Scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduler/Scheduler.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAG5C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,2BAA2B,QAAiB,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACrC,+FAA+F;IAC/F,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACnD,gFAAgF;IAChF,aAAa,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,8DAA8D;AAC9D,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACvD;AAED,qBAAa,SAAS;IAYlB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAhB7B,OAAO,CAAC,IAAI,CAA8B;IAC1C,OAAO,CAAC,GAAG,CAAsC;IACjD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,iBAAiB,CAAa;IACtC,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,mBAAmB,CAAa;IACxC,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,OAAO,CAAkB;gBAGd,MAAM,EAAE,eAAe,EACvB,QAAQ,CAAC,EAAE,QAAQ,YAAA,EACnB,SAAS,CAAC,EAAE,YAAY,YAAA,EACxB,UAAU,GAAE,MAAkB,EAC9B,SAAS,CAAC,EAAE,sBAAsB,YAAA,EAClC,SAAS,CAAC,GAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,aAAA;IAGrE,KAAK,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAoCrC;;;OAGG;IACI,MAAM,IAAI,IAAI;YAKP,UAAU;IA4NxB;;;;OAIG;YACW,mBAAmB;IAO1B,IAAI;IAgBJ,QAAQ;;;;;;;;;CAWhB"}
+{"version":3,"file":"Scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduler/Scheduler.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAG5C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,2BAA2B,QAAiB,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACrC,+FAA+F;IAC/F,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACnD,gFAAgF;IAChF,aAAa,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,8DAA8D;AAC9D,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACvD;AAED,qBAAa,SAAS;IAYlB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAhB7B,OAAO,CAAC,IAAI,CAA8B;IAC1C,OAAO,CAAC,GAAG,CAAkE;IAC7E,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,iBAAiB,CAAa;IACtC,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,mBAAmB,CAAa;IACxC,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,OAAO,CAAkB;gBAGd,MAAM,EAAE,eAAe,EACvB,QAAQ,CAAC,EAAE,QAAQ,YAAA,EACnB,SAAS,CAAC,EAAE,YAAY,YAAA,EACxB,UAAU,GAAE,MAAkB,EAC9B,SAAS,CAAC,EAAE,sBAAsB,YAAA,EAClC,SAAS,CAAC,GAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,aAAA;IAGrE,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC;IAIjE;;;;OAIG;IACI,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC;IAIhE,OAAO,CAAC,GAAG;IAsCX;;;;;;OAMG;IACI,MAAM,CAAC,cAAc,CAAC,EAAE,kBAAkB,GAAG,OAAO;YAO7C,UAAU;IA4NxB;;;;OAIG;YACW,mBAAmB;IAQ1B,IAAI;IAgBJ,QAAQ;;;;;;;;;CAWhB"}