@zintrust/core 0.1.41 → 0.1.42

package/src/proxy/sqlserver/SqlServerProxyServer.js

@@ -1,23 +1,17 @@
-import { Env } from '../../config/env.js';
-import { Logger } from '../../config/logger.js';
-import { ErrorHandler } from '../ErrorHandler.js';
-import { createProxyServer } from '../ProxyServer.js';
-import { resolveBaseConfig, resolveBaseSigningConfig, verifyRequestSignature, } from '../ProxyServerUtils.js';
-import { RequestValidator } from '../RequestValidator.js';
-import { validateSqlPayload } from '../SqlPayloadValidator.js';
+import * as Deps from '../SqlProxyServerDeps.js';
 const resolveDatabaseConfig = (overrides = {}) => {
-    const dbHost = overrides.dbHost ?? Env.get('DB_HOST_MSSQL', Env.get('DB_HOST', '127.0.0.1'));
-    const dbPort = overrides.dbPort ?? Env.getInt('DB_PORT_MSSQL', 1433);
-    const dbName = overrides.dbName ?? Env.get('DB_DATABASE_MSSQL', 'zintrust');
-    const dbUser = overrides.dbUser ?? Env.get('DB_USERNAME_MSSQL', 'sa');
-    const dbPass = overrides.dbPass ?? Env.get('DB_PASSWORD_MSSQL', '');
-    const connectionLimit = overrides.connectionLimit ?? Env.getInt('SQLSERVER_PROXY_POOL_LIMIT', 10);
+    const dbHost = overrides.dbHost ?? Deps.Env.get('DB_HOST_MSSQL', Deps.Env.get('DB_HOST', '127.0.0.1'));
+    const dbPort = overrides.dbPort ?? Deps.Env.getInt('DB_PORT_MSSQL', 1433);
+    const dbName = overrides.dbName ?? Deps.Env.get('DB_DATABASE_MSSQL', 'zintrust');
+    const dbUser = overrides.dbUser ?? Deps.Env.get('DB_USERNAME_MSSQL', 'sa');
+    const dbPass = overrides.dbPass ?? Deps.Env.get('DB_PASSWORD_MSSQL', '');
+    const connectionLimit = overrides.connectionLimit ?? Deps.Env.getInt('SQLSERVER_PROXY_POOL_LIMIT', 10);
     return { dbHost, dbPort, dbName, dbUser, dbPass, connectionLimit };
 };
 const resolveConfig = (overrides = {}) => {
-    const proxyConfig = resolveBaseConfig(overrides, 'SQLSERVER');
+    const proxyConfig = Deps.resolveBaseConfig(overrides, 'SQLSERVER');
     const dbConfig = resolveDatabaseConfig(overrides);
-    const signingConfig = resolveBaseSigningConfig(overrides, 'SQLSERVER');
+    const signingConfig = Deps.resolveBaseSigningConfig(overrides, 'SQLSERVER');
     const poolConfig = {
         server: dbConfig.dbHost,
         port: dbConfig.dbPort,
@@ -45,10 +39,11 @@ const resolveConfig = (overrides = {}) => {
             require: signingConfig.requireSigning,
             windowMs: signingConfig.signingWindowMs,
         },
+        statements: Deps.loadStatementRegistry('SQLSERVER'),
     };
 };
 const validateQueryPayload = (payload) => {
-    const base = validateSqlPayload(payload);
+    const base = Deps.validateSqlPayload(payload);
     if (!base.valid) {
         return { valid: false, error: base.error };
     }
@@ -95,42 +90,82 @@ const handleEndpoint = (path, result) => {
             },
         };
     }
-    return ErrorHandler.toProxyError(404, 'NOT_FOUND', 'Unknown endpoint');
+    if (path === '/zin/sqlserver/statement') {
+        // Statement endpoint returns query-shaped response for non-mutating SQL.
+        return { status: 200, body: { rows, rowCount: rowsAffected[0] ?? 0 } };
+    }
+    return Deps.ErrorHandler.toProxyError(404, 'NOT_FOUND', 'Unknown endpoint');
+};
+const toMutatingStatementResponse = (result) => {
+    const rowsAffected = result['rowsAffected'];
+    return {
+        status: 200,
+        body: {
+            ok: true,
+            meta: { changes: rowsAffected[0] ?? 0 },
+        },
+    };
+};
+const handleStatementRequest = async (pool, statements, requestPath, payload) => {
+    const resolved = Deps.resolveStatementOrError(statements, payload);
+    if (!resolved.ok)
+        return resolved.response;
+    try {
+        const result = await executeQuery(pool, resolved.value.sql, resolved.value.params);
+        if (!resolved.value.mutating)
+            return handleEndpoint('/zin/sqlserver/statement', result);
+        return toMutatingStatementResponse(result);
+    }
+    catch (error) {
+        Deps.Logger.error('[SqlServerProxyServer] Statement execution failed', {
+            path: requestPath,
+            statementId: resolved.value.statementId,
+            mutating: resolved.value.mutating,
+            paramsCount: resolved.value.params.length,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return Deps.ErrorHandler.toProxyError(500, 'SQLSERVER_ERROR', String(error));
+    }
+};
+const handleSqlRequest = async (pool, requestPath, payload) => {
+    const sqlValidation = validateQueryPayload(payload);
+    if (!sqlValidation.valid) {
+        const error = sqlValidation.error ?? {
+            code: 'VALIDATION_ERROR',
+            message: 'Invalid SQL payload',
+        };
+        return Deps.ErrorHandler.toProxyError(400, error.code, error.message);
+    }
+    try {
+        const result = await executeQuery(pool, sqlValidation.sql ?? '', sqlValidation.params ?? []);
+        return handleEndpoint(requestPath, result);
+    }
+    catch (error) {
+        return Deps.ErrorHandler.toProxyError(500, 'SQLSERVER_ERROR', String(error));
+    }
 };
-const createBackend = (pool) => ({
+const handleProxyRequest = async (pool, statements, request) => {
+    const validationError = Deps.validateProxyRequest(request);
+    if (validationError !== null)
+        return validationError;
+    const parsed = Deps.parseJsonBody(request.body);
+    if ('status' in parsed)
+        return parsed;
+    if (request.path === '/zin/sqlserver/statement') {
+        return handleStatementRequest(pool, statements, request.path, parsed.value);
+    }
+    return handleSqlRequest(pool, request.path, parsed.value);
+};
+const createBackend = (pool, statements) => ({
     name: 'sqlserver',
-    handle: async (request) => {
-        const methodError = RequestValidator.requirePost(request.method);
-        if (methodError) {
-            return ErrorHandler.toProxyError(405, methodError.code, methodError.message);
-        }
-        const parsed = RequestValidator.parseJson(request.body);
-        if (!parsed.ok) {
-            return ErrorHandler.toProxyError(400, parsed.error.code, parsed.error.message);
-        }
-        const sqlValidation = validateQueryPayload(parsed.value);
-        if (!sqlValidation.valid) {
-            const error = sqlValidation.error ?? {
-                code: 'VALIDATION_ERROR',
-                message: 'Invalid SQL payload',
-            };
-            return ErrorHandler.toProxyError(400, error.code, error.message);
-        }
-        try {
-            const result = await executeQuery(pool, sqlValidation.sql ?? '', sqlValidation.params ?? []);
-            return handleEndpoint(request.path, result);
-        }
-        catch (error) {
-            return ErrorHandler.toProxyError(500, 'SQLSERVER_ERROR', String(error));
-        }
-    },
+    handle: async (request) => handleProxyRequest(pool, statements, request),
     health: async () => {
         try {
             await executeQuery(pool, 'SELECT 1', []);
             return { status: 200, body: { status: 'healthy' } };
         }
         catch (error) {
-            return ErrorHandler.toProxyError(503, 'UNHEALTHY', String(error));
+            return Deps.ErrorHandler.toProxyError(503, 'UNHEALTHY', String(error));
         }
     },
     shutdown: async () => {
@@ -142,20 +177,20 @@ export const SqlServerProxyServer = Object.freeze({
     async start(overrides = {}) {
         const config = resolveConfig(overrides);
         try {
-            Logger.info(`SQL Server proxy config: proxyHost=${config.host} proxyPort=${config.port} dbHost=${String(config.poolConfig['server'])} dbPort=${String(config.poolConfig['port'])} dbName=${String(config.poolConfig['database'])} dbUser=${String(config.poolConfig['user'])}`);
+            Deps.Logger.info(`SQL Server proxy config: proxyHost=${config.host} proxyPort=${config.port} dbHost=${String(config.poolConfig['server'])} dbPort=${String(config.poolConfig['port'])} dbName=${String(config.poolConfig['database'])} dbUser=${String(config.poolConfig['user'])}`);
         }
         catch {
             // noop - logging must not block startup
         }
         const pool = await createPool(config.poolConfig);
-        const backend = createBackend(pool);
-        const proxy = createProxyServer({
+        const backend = createBackend(pool, config.statements);
+        const proxy = Deps.createProxyServer({
             host: config.host,
             port: config.port,
             maxBodyBytes: config.maxBodyBytes,
             backend,
             verify: async (req, body) => {
-                const verified = await verifyRequestSignature(req, body, config, 'SqlServerProxyServer');
+                const verified = await Deps.verifyRequestSignature(req, body, config, 'SqlServerProxyServer');
                 if (!verified.ok && verified.error) {
                     return { ok: false, status: verified.error.status, message: verified.error.message };
                 }
@@ -163,6 +198,6 @@ export const SqlServerProxyServer = Object.freeze({
             },
         });
         await proxy.start();
-        Logger.info(`✓ SQL Server proxy listening on ${config.host}:${config.port}`);
+        Deps.Logger.info(`✓ SQL Server proxy listening on ${config.host}:${config.port}`);
     },
 });

package/src/proxy.d.ts

@@ -0,0 +1,4 @@
+export { ErrorHandler } from './proxy/ErrorHandler';
+export { RequestValidator } from './proxy/RequestValidator';
+export { SigningService } from './proxy/SigningService';
+//# sourceMappingURL=proxy.d.ts.map

package/src/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/src/proxy.js

@@ -0,0 +1,3 @@
+export { ErrorHandler } from './proxy/ErrorHandler.js';
+export { RequestValidator } from './proxy/RequestValidator.js';
+export { SigningService } from './proxy/SigningService.js';

package/src/scheduler/Schedule.d.ts

@@ -0,0 +1,36 @@
+import type { ISchedule, IScheduleBackoffPolicy } from './types';
+type CronOptions = {
+    timezone?: string;
+};
+type WithoutOverlappingOptions = {
+    provider?: string;
+    ttlMs?: number;
+    key?: string;
+};
+export type ScheduleBuilderApi = Readonly<{
+    everyMinute: () => ScheduleBuilderApi;
+    everyMinutes: (minutes: number) => ScheduleBuilderApi;
+    everyHour: () => ScheduleBuilderApi;
+    everyHours: (hours: number) => ScheduleBuilderApi;
+    intervalMs: (ms: number) => ScheduleBuilderApi;
+    cron: (expr: string, options?: CronOptions) => ScheduleBuilderApi;
+    timezone: (tz: string) => ScheduleBuilderApi;
+    jitterMs: (ms: number) => ScheduleBuilderApi;
+    backoff: (policy: IScheduleBackoffPolicy) => ScheduleBuilderApi;
+    leaderOnly: () => ScheduleBuilderApi;
+    runOnStart: () => ScheduleBuilderApi;
+    enabledWhen: (value: boolean) => ScheduleBuilderApi;
+    withoutOverlapping: (options?: WithoutOverlappingOptions) => ScheduleBuilderApi;
+    build: () => ISchedule;
+}>;
+export declare const Schedule: Readonly<{
+    define(name: string, handler: ISchedule["handler"]): ScheduleBuilderApi;
+}>;
+export declare const ScheduleBuilder: Readonly<{
+    create(input: {
+        name: string;
+        handler: ISchedule["handler"];
+    }): ScheduleBuilderApi;
+}>;
+export default Schedule;
+//# sourceMappingURL=Schedule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Schedule.d.ts","sourceRoot":"","sources":["../../../src/scheduler/Schedule.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1E,KAAK,WAAW,GAAG;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,KAAK,yBAAyB,GAAG;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,WAAW,EAAE,MAAM,kBAAkB,CAAC;IACtC,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,kBAAkB,CAAC;IACtD,SAAS,EAAE,MAAM,kBAAkB,CAAC;IACpC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,kBAAkB,CAAC;IAClD,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,kBAAkB,CAAC;IAC/C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,kBAAkB,CAAC;IAClE,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,kBAAkB,CAAC;IAC7C,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,kBAAkB,CAAC;IAC7C,OAAO,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,kBAAkB,CAAC;IAChE,UAAU,EAAE,MAAM,kBAAkB,CAAC;IACrC,UAAU,EAAE,MAAM,kBAAkB,CAAC;IACrC,WAAW,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,kBAAkB,CAAC;IACpD,kBAAkB,EAAE,CAAC,OAAO,CAAC,EAAE,yBAAyB,KAAK,kBAAkB,CAAC;IAChF,KAAK,EAAE,MAAM,SAAS,CAAC;CACxB,CAAC,CAAC;AA4HH,eAAO,MAAM,QAAQ;iBACN,MAAM,WAAW,SAAS,CAAC,SAAS,CAAC,GAAG,kBAAkB;EAGvE,CAAC;AAqFH,eAAO,MAAM,eAAe;kBACZ;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAA;KAAE,GAAG,kBAAkB;EAQlF,CAAC;AAEH,eAAe,QAAQ,CAAC"}

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"}