@zintrust/core 0.1.40 → 0.1.42

package/src/scheduler/Schedule.js

@@ -0,0 +1,197 @@
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { ZintrustLang } from '../lang/lang.js';
+import { createAdvancedQueue } from '../tools/queue/AdvancedQueue.js';
+import { getLockProvider } from '../tools/queue/LockProvider.js';
+const toIntervalMs = (ms) => {
+    if (!Number.isFinite(ms) || ms <= 0)
+        return 0;
+    return Math.floor(ms);
+};
+const normalizeOptionalString = (value) => {
+    const s = typeof value === 'string' ? value.trim() : '';
+    return s.length > 0 ? s : undefined;
+};
+const toPositiveInt = (value) => {
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return Math.floor(n);
+};
+const resolveLockProvider = (providerName) => {
+    const name = providerName.trim().toLowerCase();
+    if (name.length === 0)
+        return undefined;
+    // Ensure provider is registered. createAdvancedQueue triggers lock-provider registration.
+    createAdvancedQueue({
+        name: ZintrustLang.CLI_LOCKS,
+        connection: undefined,
+        defaultDedupTtl: Env.getInt('SCHEDULE_OVERLAP_LOCK_TTL_MS', 300000),
+        lockProvider: name,
+    });
+    return getLockProvider(name);
+};
+const normalizeBackoffFactor = (factor) => {
+    if (factor === undefined)
+        return undefined;
+    return Number.isFinite(factor) ? factor : undefined;
+};
+const wrapWithoutOverlapping = (scheduleName, handler, options) => {
+    const providerName = (options.provider ?? 'redis').trim();
+    const lockKey = (options.key ?? `schedule:${scheduleName}`).trim();
+    const ttlMs = Env.getInt('SCHEDULE_OVERLAP_LOCK_TTL_MS', options.ttlMs ?? 300000);
+    const acquireTimeoutMs = Env.getInt('SCHEDULE_OVERLAP_LOCK_ACQUIRE_TIMEOUT_MS', 2000);
+    const withTimeout = async (promise, timeoutMs) => {
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            return promise;
+        let timeoutId;
+        try {
+            return await Promise.race([
+                promise,
+                new Promise((_, reject) => {
+                    timeoutId = globalThis.setTimeout(() => {
+                        // eslint-disable-next-line no-restricted-syntax
+                        reject(new Error('Lock acquire timed out'));
+                    }, timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timeoutId !== undefined)
+                globalThis.clearTimeout(timeoutId);
+        }
+    };
+    return async (kernel) => {
+        const provider = resolveLockProvider(providerName);
+        if (!provider) {
+            Logger.warn('Schedule withoutOverlapping requested but lock provider not available; running anyway', {
+                schedule: scheduleName,
+                provider: providerName,
+            });
+            await handler(kernel);
+            return;
+        }
+        let lock;
+        try {
+            lock = await withTimeout(provider.acquire(lockKey, { ttl: ttlMs }), acquireTimeoutMs);
+        }
+        catch (error) {
+            Logger.warn('Schedule lock acquire failed; running anyway', {
+                schedule: scheduleName,
+                provider: providerName,
+                timeoutMs: acquireTimeoutMs,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            await handler(kernel);
+            return;
+        }
+        if (!lock.acquired) {
+            Logger.info(`Skipping overlapping run for schedule: ${scheduleName}`);
+            return;
+        }
+        try {
+            await handler(kernel);
+        }
+        finally {
+            try {
+                await provider.release(lock);
+            }
+            catch {
+                // best-effort
+            }
+        }
+    };
+};
+export const Schedule = Object.freeze({
+    define(name, handler) {
+        return ScheduleBuilder.create({ name, handler });
+    },
+});
+const createScheduleApi = (state) => {
+    const api = Object.freeze({
+        everyMinute: () => api.everyMinutes(1),
+        everyMinutes: (minutes) => {
+            const resolved = Math.max(1, Math.floor(minutes));
+            state.intervalMs = resolved * 60_000;
+            return api;
+        },
+        everyHour: () => api.everyHours(1),
+        everyHours: (hours) => {
+            const resolved = Math.max(1, Math.floor(hours));
+            state.intervalMs = resolved * 3_600_000;
+            return api;
+        },
+        intervalMs: (ms) => {
+            state.intervalMs = toIntervalMs(ms);
+            return api;
+        },
+        cron: (expr, options) => {
+            state.cron = normalizeOptionalString(expr);
+            if (options?.timezone !== undefined) {
+                state.timezone = normalizeOptionalString(options.timezone);
+            }
+            return api;
+        },
+        timezone: (tz) => {
+            state.timezone = normalizeOptionalString(tz);
+            return api;
+        },
+        jitterMs: (ms) => {
+            state.jitterMs = toPositiveInt(ms);
+            return api;
+        },
+        backoff: (policy) => {
+            state.backoff = {
+                initialMs: toPositiveInt(policy.initialMs) ?? 0,
+                maxMs: toPositiveInt(policy.maxMs) ?? 0,
+                factor: normalizeBackoffFactor(policy.factor),
+            };
+            return api;
+        },
+        leaderOnly: () => {
+            state.leaderOnly = true;
+            return api;
+        },
+        runOnStart: () => {
+            state.runOnStart = true;
+            return api;
+        },
+        enabledWhen: (value) => {
+            state.enabled = value;
+            return api;
+        },
+        withoutOverlapping: (options) => {
+            state.overlap = options ?? {};
+            return api;
+        },
+        build: () => {
+            const handler = state.overlap === undefined
+                ? state.handler
+                : wrapWithoutOverlapping(state.name, state.handler, state.overlap);
+            const schedule = {
+                name: state.name,
+                intervalMs: state.intervalMs,
+                cron: state.cron,
+                timezone: state.timezone,
+                jitterMs: state.jitterMs,
+                backoff: state.backoff,
+                leaderOnly: state.leaderOnly,
+                handler,
+                enabled: state.enabled,
+                runOnStart: state.runOnStart,
+            };
+            return schedule;
+        },
+    });
+    return api;
+};
+export const ScheduleBuilder = Object.freeze({
+    create(input) {
+        const state = {
+            name: input.name,
+            handler: input.handler,
+        };
+        return createScheduleApi(state);
+    },
+});
+export default Schedule;

package/src/scheduler/ScheduleHttpGateway.d.ts

@@ -0,0 +1,8 @@
+import type { IRouter } from '../routes/Router';
+export declare const ScheduleHttpGateway: Readonly<{
+    create(): {
+        registerRoutes: (router: IRouter) => void;
+    };
+}>;
+export default ScheduleHttpGateway;
+//# sourceMappingURL=ScheduleHttpGateway.d.ts.map

package/src/scheduler/ScheduleHttpGateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleHttpGateway.d.ts","sourceRoot":"","sources":["../../../src/scheduler/ScheduleHttpGateway.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AA8QnD,eAAO,MAAM,mBAAmB;cACpB;QAAE,cAAc,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE;EAWvD,CAAC;AAEH,eAAe,mBAAmB,CAAC"}

package/src/scheduler/ScheduleHttpGateway.js

@@ -0,0 +1,196 @@
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { Router } from '../routes/Router.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { SchedulerRuntime } from './SchedulerRuntime.js';
+import { SignedRequest } from '../security/SignedRequest.js';
+const nonces = new Map();
+const nowMs = () => Date.now();
+const normalizePath = (value) => {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return '/api/_sys/schedule/rpc';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+const parseMiddleware = (value) => value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+const readSettings = () => {
+    const configuredSecret = Env.get('SCHEDULE_HTTP_PROXY_KEY', '').trim();
+    const secret = configuredSecret === '' ? Env.APP_KEY : configuredSecret;
+    return {
+        basePath: normalizePath(Env.get('SCHEDULE_HTTP_PROXY_PATH', '/api/_sys/schedule/rpc')),
+        keyId: Env.get('SCHEDULE_HTTP_PROXY_KEY_ID', Env.APP_NAME || 'zintrust').trim(),
+        secret,
+        signingWindowMs: Env.getInt('SCHEDULE_HTTP_PROXY_MAX_SKEW_MS', 60000),
+        nonceTtlMs: Env.getInt('SCHEDULE_HTTP_PROXY_NONCE_TTL_MS', 120000),
+        middleware: parseMiddleware(Env.get('SCHEDULE_HTTP_PROXY_MIDDLEWARE', '')),
+    };
+};
+const cleanupExpiredNonces = () => {
+    const current = nowMs();
+    for (const [nonceKey, expiresAt] of nonces.entries()) {
+        if (expiresAt <= current)
+            nonces.delete(nonceKey);
+    }
+};
+// eslint-disable-next-line @typescript-eslint/require-await
+const storeNonce = async (keyId, nonce, ttlMs) => {
+    cleanupExpiredNonces();
+    const nonceKey = `${keyId}:${nonce}`;
+    if (nonces.has(nonceKey))
+        return false;
+    nonces.set(nonceKey, nowMs() + Math.max(ttlMs, 1));
+    return true;
+};
+const getBodyRecord = (req) => {
+    const body = req.getBody?.() ?? req.body;
+    if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
+        return body;
+    }
+    return {};
+};
+const getRawBody = (req) => {
+    const rawText = req.context?.['rawBodyText'];
+    if (typeof rawText === 'string')
+        return rawText;
+    return JSON.stringify(getBodyRecord(req));
+};
+const toIncomingHeaders = (req) => {
+    const headers = req.getHeaders();
+    const normalize = (value) => {
+        if (Array.isArray(value))
+            return value.join(',');
+        return value;
+    };
+    return {
+        'x-zt-key-id': normalize(headers['x-zt-key-id']),
+        'x-zt-nonce': normalize(headers['x-zt-nonce']),
+        'x-zt-timestamp': normalize(headers['x-zt-timestamp']),
+        'x-zt-body-sha256': normalize(headers['x-zt-body-sha256']),
+        'x-zt-signature': normalize(headers['x-zt-signature']),
+        'content-type': normalize(headers['content-type']),
+    };
+};
+const parseRequest = (req) => {
+    const body = getBodyRecord(req);
+    const action = String(body['action'] ?? '')
+        .trim()
+        .toLowerCase();
+    const requestId = String(body['requestId'] ?? '').trim();
+    if (requestId.length === 0) {
+        throw ErrorFactory.createValidationError('requestId is required');
+    }
+    if (action !== 'list' && action !== 'run') {
+        throw ErrorFactory.createValidationError('Invalid action');
+    }
+    const payload = typeof body['payload'] === 'object' && body['payload'] !== null
+        ? body['payload']
+        : undefined;
+    return {
+        action: action,
+        requestId,
+        payload,
+    };
+};
+const ok = (requestId, result) => ({
+    ok: true,
+    requestId,
+    result,
+    error: null,
+});
+const fail = (requestId, code, message, details) => ({
+    ok: false,
+    requestId,
+    result: null,
+    error: { code, message, details },
+});
+const listSchedules = async () => {
+    const rows = await SchedulerRuntime.listWithState();
+    return rows.map(({ schedule, state }) => ({
+        name: schedule.name,
+        intervalMs: schedule.intervalMs,
+        cron: schedule.cron,
+        timezone: schedule.timezone,
+        enabled: schedule.enabled,
+        runOnStart: schedule.runOnStart,
+        state,
+    }));
+};
+const verifyRequest = async (req, bodyText, settings) => {
+    if (settings.keyId.trim() === '' || settings.secret.trim() === '') {
+        return {
+            ok: false,
+            status: 500,
+            code: 'CONFIG_ERROR',
+            message: 'Schedule HTTP gateway signing credentials are not configured',
+        };
+    }
+    const url = new URL(req.getPath(), 'http://localhost');
+    const verifyResult = await SignedRequest.verify({
+        method: req.getMethod(),
+        url,
+        body: bodyText,
+        headers: toIncomingHeaders(req),
+        nowMs: nowMs(),
+        windowMs: settings.signingWindowMs,
+        verifyNonce: async (keyId, nonce) => storeNonce(keyId, nonce, settings.nonceTtlMs),
+        getSecretForKeyId: (keyId) => {
+            if (keyId === settings.keyId)
+                return settings.secret;
+            return undefined;
+        },
+    });
+    if (verifyResult.ok === true)
+        return { ok: true };
+    const errorCode = 'code' in verifyResult ? verifyResult.code : 'INVALID_SIGNATURE';
+    const errorMessage = 'message' in verifyResult ? verifyResult.message : 'Invalid signature';
+    const status = errorCode === 'EXPIRED' || errorCode === 'REPLAYED' ? 401 : 403;
+    return { ok: false, status, code: errorCode, message: errorMessage };
+};
+const handleRpc = async (req, res) => {
+    const settings = readSettings();
+    const rawBody = getRawBody(req);
+    const body = getBodyRecord(req);
+    const requestId = typeof body['requestId'] === 'string' && String(body['requestId']).trim() !== ''
+        ? String(body['requestId'])
+        : 'unknown';
+    const auth = await verifyRequest(req, rawBody, settings);
+    if (auth.ok === false) {
+        res.status(auth.status).json(fail(requestId, auth.code, auth.message));
+        return;
+    }
+    const parsed = parseRequest(req);
+    try {
+        if (parsed.action === 'list') {
+            res.json(ok(parsed.requestId, await listSchedules()));
+            return;
+        }
+        const name = String(parsed.payload?.name ?? '').trim();
+        if (name.length === 0) {
+            res.status(400).json(fail(parsed.requestId, 'VALIDATION_ERROR', 'payload.name is required'));
+            return;
+        }
+        await SchedulerRuntime.runOnce(name);
+        res.json(ok(parsed.requestId, { ran: true, name }));
+    }
+    catch (error) {
+        Logger.error('Schedule RPC failed', error);
+        res.status(500).json(fail(parsed.requestId, 'INTERNAL_ERROR', 'Schedule RPC failed', {
+            message: error instanceof Error ? error.message : String(error),
+        }));
+    }
+};
+export const ScheduleHttpGateway = Object.freeze({
+    create() {
+        const settings = readSettings();
+        const options = settings.middleware.length > 0 ? { middleware: settings.middleware } : undefined;
+        return Object.freeze({
+            registerRoutes(router) {
+                Router.post(router, settings.basePath, handleRpc, options);
+            },
+        });
+    },
+});
+export default ScheduleHttpGateway;

package/src/scheduler/ScheduleRunner.d.ts

@@ -2,6 +2,7 @@
  * ScheduleRunner
  * Lightweight, zero-dependency schedule runner for long-running runtimes
  */
+import { type ScheduleRunState } from './state/ScheduleStateStore';
 import type { ISchedule, IScheduleKernel } from './types';
 type ScheduleRunner = {
     register: (schedule: ISchedule) => void;
@@ -9,6 +10,11 @@ type ScheduleRunner = {
     stop: (timeoutMs?: number) => Promise<void>;
     list: () => ISchedule[];
     runOnce: (name: string, kernel?: IScheduleKernel) => Promise<void>;
+    getState: (name: string) => Promise<ScheduleRunState | null>;
+    listStates: () => Promise<Array<{
+        name: string;
+        state: ScheduleRunState;
+    }>>;
 };
 export declare const create: () => Readonly<ScheduleRunner>;
 declare const _default: {

package/src/scheduler/ScheduleRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScheduleRunner.d.ts","sourceRoot":"","sources":["../../../src/scheduler/ScheduleRunner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAgBnE,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;IACxC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1C,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,SAAS,EAAE,CAAC;IACxB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE,CAAC;AAoKF,eAAO,MAAM,MAAM,QAAO,QAAQ,CAAC,cAAc,CAuBhD,CAAC;;kBAvBwB,QAAQ,CAAC,cAAc,CAAC;;AAyBlD,wBAA0B"}
+{"version":3,"file":"ScheduleRunner.d.ts","sourceRoot":"","sources":["../../../src/scheduler/ScheduleRunner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAkBnE,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;IACxC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1C,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,SAAS,EAAE,CAAC;IACxB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC7D,UAAU,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAA;KAAE,CAAC,CAAC,CAAC;CAC7E,CAAC;AA6VF,eAAO,MAAM,MAAM,QAAO,QAAQ,CAAC,cAAc,CA6BhD,CAAC;;kBA7BwB,QAAQ,CAAC,cAAc,CAAC;;AA+BlD,wBAA0B"}