@rebasepro/server-core 0.7.0 → 0.8.0

package/dist/cron/cron-scheduler.d.ts

@@ -0,0 +1,106 @@
+import type { CronJobStatus, CronJobLogEntry } from "@rebasepro/types";
+import type { RebaseClient } from "@rebasepro/types";
+import type { LoadedCronJob } from "./cron-loader";
+import type { CronStore } from "./cron-store";
+/**
+ * Validates a standard 5-field cron expression structurally and semantically.
+ * Returns `{ valid: true }` or `{ valid: false, reason: string }`.
+ */
+export declare function validateCronExpression(schedule: string): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+export declare class CronScheduler {
+    private jobs;
+    private started;
+    private store?;
+    private client?;
+    /**
+     * Set the RebaseClient instance to make it available to cron job handlers.
+     */
+    setClient(client: RebaseClient): void;
+    /**
+     * Attach a persistence store for cron logs.
+     * When set, execution logs are written to the database after each run,
+     * and counters are seeded from the database on start.
+     */
+    setStore(store: CronStore): void;
+    /**
+     * Register a batch of loaded cron jobs.
+     *
+     * If the scheduler is already started, newly registered jobs are
+     * automatically scheduled (so late-registered jobs don't sit idle).
+     *
+     * Validates the cron schedule on registration — invalid schedules
+     * are rejected with a warning and the job is NOT registered.
+     */
+    registerJobs(loadedJobs: LoadedCronJob[]): void;
+    /**
+     * Start the scheduler — begins ticking all enabled jobs.
+     */
+    start(): void;
+    /**
+     * Stop the scheduler and clear all timers.
+     *
+     * Currently-executing handlers run to completion (they are async),
+     * but no further scheduling occurs after stop.
+     */
+    stop(): void;
+    /**
+     * List all registered jobs with their current status.
+     */
+    listJobs(): CronJobStatus[];
+    /**
+     * Get a single job status by ID.
+     */
+    getJob(id: string): CronJobStatus | undefined;
+    /**
+     * Get log entries for a job.
+     */
+    getJobLogs(id: string, limit?: number): CronJobLogEntry[];
+    /**
+     * Get log entries for a job from the database (if store is available).
+     * Falls back to in-memory logs if no store is configured.
+     */
+    getJobLogsFromDb(id: string, limit?: number): Promise<CronJobLogEntry[]>;
+    /**
+     * Enable or disable a job at runtime.
+     */
+    setJobEnabled(id: string, enabled: boolean): CronJobStatus | undefined;
+    /**
+     * Manually trigger a job execution immediately.
+     *
+     * Returns `undefined` if the job doesn't exist.
+     * If the job is currently executing, returns the log entry with
+     * a `skipped: true` result rather than running concurrently.
+     */
+    triggerJob(id: string): Promise<CronJobLogEntry | undefined>;
+    /**
+     * Schedule the next execution for a job.
+     *
+     * Safety guarantees:
+     * 1. Clears any existing timer first (prevents leaked/duplicate timers)
+     * 2. Enforces a minimum delay to prevent tight loops from jitter
+     * 3. Unref's the timer so it doesn't prevent process exit
+     * 4. Re-checks enabled & started state before executing
+     * 5. Concurrency guard prevents overlapping handler executions
+     */
+    private scheduleNext;
+    /**
+     * Stop a single job's timer and clear its next run state.
+     */
+    private stopJob;
+    /**
+     * Execute a job's handler with full isolation and safety.
+     *
+     * - Sets a concurrency flag to prevent overlapping runs
+     * - Wraps handler in a timeout race
+     * - Captures all logs, errors, and results
+     * - Persists to store (non-blocking) if available
+     * - Always restores state even on catastrophic errors
+     */
+    private executeJob;
+    private toStatus;
+}

package/dist/cron/cron-store.d.ts

@@ -0,0 +1,32 @@
+import type { CronJobLogEntry } from "@rebasepro/types";
+import type { DataDriver } from "@rebasepro/types";
+/**
+ * Persistence layer for cron job execution logs.
+ *
+ * Uses the DataDriver's `admin.executeSql` capability to store logs in a
+ * `rebase.cron_logs` table. Falls back gracefully if the driver doesn't
+ * support SQL (e.g. MongoDB) — in that case, no persistence occurs.
+ */
+export interface CronStore {
+    /** Ensure the backing table exists. Called once on startup. */
+    ensureTable(): Promise<void>;
+    /** Persist a single log entry after execution. */
+    insertLog(entry: CronJobLogEntry): Promise<void>;
+    /**
+     * Fetch the most recent logs for a job.
+     * @param jobId  The job identifier
+     * @param limit  Max entries to return (default 50)
+     * @returns Logs sorted newest-first
+     */
+    fetchLogs(jobId: string, limit?: number): Promise<CronJobLogEntry[]>;
+    /**
+     * Fetch aggregate stats for all jobs (totalRuns, totalFailures, lastRunAt).
+     * Used to seed in-memory counters on startup.
+     */
+    fetchJobStats(): Promise<Map<string, {
+        totalRuns: number;
+        totalFailures: number;
+        lastRunAt?: string;
+    }>>;
+}
+export declare function createCronStore(driver: DataDriver): CronStore | undefined;

package/dist/cron/index.d.ts

@@ -0,0 +1,6 @@
+export { loadCronJobsFromDirectory } from "./cron-loader";
+export type { LoadedCronJob } from "./cron-loader";
+export { CronScheduler, validateCronExpression } from "./cron-scheduler";
+export { createCronRoutes } from "./cron-routes";
+export { createCronStore } from "./cron-store";
+export type { CronStore } from "./cron-store";

package/dist/db/interfaces.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Database Abstraction Interfaces
+ *
+ * These interfaces define the contracts that any database backend must implement
+ * to be used with Rebase. This allows for pluggable database backends like
+ * PostgreSQL, MongoDB, MySQL, etc.
+ */
+import { DatabaseConnection, QueryFilter, FetchCollectionOptions, SearchOptions, CountOptions, ConditionBuilder, ConditionBuilderStatic, EntityRepository, CollectionSubscriptionConfig, EntitySubscriptionConfig, RealtimeProvider, CollectionRegistryInterface, DataTransformer, BackendConfig, BackendInstance, BackendFactory } from "@rebasepro/types";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { PgTransaction } from "drizzle-orm/pg-core";
+/**
+ * Type representing either a direct database connection or a transaction.
+ * Used to allow services to operate within a transaction context.
+ * Note: `any` is intentional here — it represents a Drizzle client with
+ * a dynamic schema, enabling `db.query[tableName]` access without casts.
+ */
+export type DrizzleClient = NodePgDatabase<Record<string, unknown>> | PgTransaction<any, any, any>;
+export type { DatabaseConnection, QueryFilter, FetchCollectionOptions, SearchOptions, CountOptions, ConditionBuilder, ConditionBuilderStatic, EntityRepository, CollectionSubscriptionConfig, EntitySubscriptionConfig, RealtimeProvider, CollectionRegistryInterface, DataTransformer, BackendConfig, BackendInstance, BackendFactory };