@rebasepro/server 0.25.1 → 0.27.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/{GCSStorageController-CRd9bFrc.js → GCSStorageController-BUClIfp0.js} +40 -3
- package/dist/GCSStorageController-BUClIfp0.js.map +1 -0
- package/dist/{S3StorageController-D00EFa5P.js → S3StorageController-CixCQEky.js} +58 -10
- package/dist/S3StorageController-CixCQEky.js.map +1 -0
- package/dist/access-BFAUvsSs.js +1897 -0
- package/dist/access-BFAUvsSs.js.map +1 -0
- package/dist/api/branch-routes.d.ts +25 -0
- package/dist/api/live-schema-routes.d.ts +10 -0
- package/dist/api/rest/api-generator.d.ts +9 -1
- package/dist/api/rest/idempotency.d.ts +15 -1
- package/dist/api/root-error-handler.d.ts +6 -5
- package/dist/api/types.d.ts +12 -0
- package/dist/{ast-schema-editor-mCeSC03x.js → ast-schema-editor-madTa9Hh.js} +2 -2
- package/dist/{ast-schema-editor-mCeSC03x.js.map → ast-schema-editor-madTa9Hh.js.map} +1 -1
- package/dist/auth/access.d.ts +10 -0
- package/dist/auth/adapter-middleware.d.ts +2 -1
- package/dist/auth/adapter-service-key.d.ts +24 -0
- package/dist/auth/admin-users-route.d.ts +3 -0
- package/dist/auth/api-keys/api-key-middleware.d.ts +21 -1
- package/dist/auth/api-keys/api-key-store.d.ts +8 -1
- package/dist/auth/api-keys/key-grant.d.ts +18 -1
- package/dist/auth/apple-oauth.d.ts +39 -10
- package/dist/auth/capabilities.d.ts +2 -0
- package/dist/auth/expired-token-sweep.d.ts +5 -0
- package/dist/auth/impersonation.d.ts +3 -1
- package/dist/auth/interfaces.d.ts +55 -0
- package/dist/auth/jwt.d.ts +8 -2
- package/dist/auth/oauth-signin-policy.d.ts +21 -35
- package/dist/auth/rls-scope.d.ts +17 -7
- package/dist/auth/rls-simulator-routes.d.ts +51 -0
- package/dist/auth/simulation-read-only.d.ts +28 -0
- package/dist/auth/simulation.d.ts +141 -0
- package/dist/auth/sql-rate-limit-store.d.ts +15 -1
- package/dist/{auth-Dkvo2tTJ.js → auth-DDXPw0mn.js} +527 -1883
- package/dist/auth-DDXPw0mn.js.map +1 -0
- package/dist/auth_adapter-B7RUMk6e.js +89 -0
- package/dist/auth_adapter-B7RUMk6e.js.map +1 -0
- package/dist/backend/create-backend.d.ts +6 -0
- package/dist/backend/options.d.ts +38 -5
- package/dist/{backend-DTAOsLQc.js → backend-CaG_Jyso.js} +9 -2
- package/dist/backend-CaG_Jyso.js.map +1 -0
- package/dist/{backup-B9m3cb3X.js → backup-B6brPSeB.js} +6 -6
- package/dist/{backup-B9m3cb3X.js.map → backup-B6brPSeB.js.map} +1 -1
- package/dist/boot/boot.d.ts +2 -15
- package/dist/boot/ddl-bootstrap.d.ts +34 -0
- package/dist/boot/env.d.ts +12 -0
- package/dist/boot/fetch-bundle.d.ts +5 -1
- package/dist/boot/provision-only.d.ts +23 -0
- package/dist/boot/provision.d.ts +53 -2
- package/dist/boot/role.d.ts +2 -0
- package/dist/boot/schema-change-recorder.d.ts +45 -0
- package/dist/boot/security-headers.d.ts +22 -0
- package/dist/branch-routes-B2vvEx53.js +84 -0
- package/dist/branch-routes-B2vvEx53.js.map +1 -0
- package/dist/{contract-routes-CsFXW7j4.js → contract-routes-CU2A3JnF.js} +2 -2
- package/dist/{contract-routes-CsFXW7j4.js.map → contract-routes-CU2A3JnF.js.map} +1 -1
- package/dist/cron/cron-loader.d.ts +4 -0
- package/dist/cron/cron-store.d.ts +8 -1
- package/dist/{cron-loader-Dj6lA4HQ.js → cron-loader-CC1Jy_KN.js} +14 -6
- package/dist/cron-loader-CC1Jy_KN.js.map +1 -0
- package/dist/{cron-routes-CwbLZguO.js → cron-routes-BK60Rn1r.js} +3 -3
- package/dist/{cron-routes-CwbLZguO.js.map → cron-routes-BK60Rn1r.js.map} +1 -1
- package/dist/{cron-scheduler-B04ACoUE.js → cron-scheduler-DyCjPlQR.js} +40 -27
- package/dist/cron-scheduler-DyCjPlQR.js.map +1 -0
- package/dist/{cron-store-DkyfuLOH.js → cron-store-DLn11M8H.js} +10 -9
- package/dist/cron-store-DLn11M8H.js.map +1 -0
- package/dist/{strings.es-BeZWAodn.js → data_driver-D0mg1Y_x.js} +2 -90
- package/dist/data_driver-D0mg1Y_x.js.map +1 -0
- package/dist/{ddl-bootstrap-Ck20GSIX.js → ddl-bootstrap-CjRrn12l.js} +91 -2
- package/dist/ddl-bootstrap-CjRrn12l.js.map +1 -0
- package/dist/deploy/pod-contract.d.ts +1 -1
- package/dist/{load-failure-L5hvfDoG.js → dynamic-import-Bi3XK5y-.js} +30 -18
- package/dist/dynamic-import-Bi3XK5y-.js.map +1 -0
- package/dist/email/dev-sink.d.ts +6 -0
- package/dist/email/index.d.ts +1 -1
- package/dist/{soft-delete-params-BmlVwecC.js → field-access-DYsvjI_P.js} +27 -57
- package/dist/field-access-DYsvjI_P.js.map +1 -0
- package/dist/{filter-dialect-O1HK6Nvr.js → filter-dialect-TrKFWLqT.js} +3 -3
- package/dist/{filter-dialect-O1HK6Nvr.js.map → filter-dialect-TrKFWLqT.js.map} +1 -1
- package/dist/{function-loader-KKDqTcIr.js → function-loader-eFigStYX.js} +34 -18
- package/dist/function-loader-eFigStYX.js.map +1 -0
- package/dist/functions/function-loader.d.ts +5 -0
- package/dist/functions/hono-like.d.ts +12 -0
- package/dist/functions/index.js +19 -1
- package/dist/functions/index.js.map +1 -1
- package/dist/functions/request-timeout.d.ts +3 -3
- package/dist/history/history-routes.d.ts +6 -0
- package/dist/history/retention-sweep.d.ts +5 -0
- package/dist/{history-recorder-B2rkuhuy.js → history-recorder-Bsau7h4X.js} +6 -6
- package/dist/history-recorder-Bsau7h4X.js.map +1 -0
- package/dist/{history-store-DPofGVDp.js → history-store-BQz5YCkW.js} +26 -2
- package/dist/history-store-BQz5YCkW.js.map +1 -0
- package/dist/index.d.ts +4 -2
- package/dist/index.es.js +3026 -611
- package/dist/index.es.js.map +1 -1
- package/dist/init/docs.d.ts +1 -1
- package/dist/init/health.d.ts +13 -0
- package/dist/init/process-safety.d.ts +4 -3
- package/dist/init/shutdown.d.ts +8 -0
- package/dist/init.d.ts +6 -1
- package/dist/jobs/job-store.d.ts +8 -1
- package/dist/{jobs-h1WRq3cp.js → jobs-Co6Ni5HP.js} +6 -6
- package/dist/jobs-Co6Ni5HP.js.map +1 -0
- package/dist/{jwt-D3oFauZI.js → jwt-rDS0884_.js} +4 -3
- package/dist/{jwt-D3oFauZI.js.map → jwt-rDS0884_.js.map} +1 -1
- package/dist/{keys-COzQ2aE8.js → keys-BXcdRNhJ.js} +2 -2
- package/dist/{keys-COzQ2aE8.js.map → keys-BXcdRNhJ.js.map} +1 -1
- package/dist/mcp/consent-page.d.ts +38 -1
- package/dist/mcp/mcp-routes.d.ts +9 -0
- package/dist/mcp/mcp-tools.d.ts +7 -1
- package/dist/mcp/oauth-store.d.ts +12 -5
- package/dist/metrics/history-recorder.d.ts +4 -1
- package/dist/metrics/history-store.d.ts +8 -0
- package/dist/metrics/index.d.ts +8 -0
- package/dist/metrics/realtime.d.ts +25 -0
- package/dist/{offline-BrqCRgih-BtDB1ecy.js → offline-AvuEcg7u-DFHL98OT.js} +127 -40
- package/dist/offline-AvuEcg7u-DFHL98OT.js.map +1 -0
- package/dist/{offline-store-BhYXViha-BW5j1We_.js → offline-store-BhYXViha-YTmjBpo2.js} +5 -5
- package/dist/{offline-store-BhYXViha-BW5j1We_.js.map → offline-store-BhYXViha-YTmjBpo2.js.map} +1 -1
- package/dist/{openapi-generator-BjHr6upl.js → openapi-generator-CyxEtYEX.js} +61 -22
- package/dist/openapi-generator-CyxEtYEX.js.map +1 -0
- package/dist/{proxy-CH8Jsovg.js → proxy-BYir8tWK.js} +4 -6
- package/dist/proxy-BYir8tWK.js.map +1 -0
- package/dist/{query-parser-otFZqJsC.js → query-parser-CDXWf2hH.js} +6 -5
- package/dist/{query-parser-otFZqJsC.js.map → query-parser-CDXWf2hH.js.map} +1 -1
- package/dist/{request-timeout-59crS-9u.js → request-timeout-DVjo-c_8.js} +4 -4
- package/dist/request-timeout-DVjo-c_8.js.map +1 -0
- package/dist/rls-simulator-routes-bEY7-5-u.js +190 -0
- package/dist/rls-simulator-routes-bEY7-5-u.js.map +1 -0
- package/dist/schema-edit/deployed-schema-guard.d.ts +47 -0
- package/dist/{schema-editor-routes-Bsut0bCC.js → schema-editor-routes-Dc3DU_jm.js} +3 -3
- package/dist/{schema-editor-routes-Bsut0bCC.js.map → schema-editor-routes-Dc3DU_jm.js.map} +1 -1
- package/dist/services/routed-realtime-service.d.ts +1 -1
- package/dist/soft-delete-params-BRONCOA2.js +59 -0
- package/dist/soft-delete-params-BRONCOA2.js.map +1 -0
- package/dist/{sql-export-routes-DmB_uZ4l.js → sql-export-routes-QycX8W8S.js} +38 -4
- package/dist/sql-export-routes-QycX8W8S.js.map +1 -0
- package/dist/{src-D5Y3N-S4.js → src-Bh9LRPb9.js} +21 -2
- package/dist/{src-D5Y3N-S4.js.map → src-Bh9LRPb9.js.map} +1 -1
- package/dist/storage/GCSStorageController.d.ts +11 -1
- package/dist/storage/LocalStorageController.d.ts +16 -4
- package/dist/storage/S3StorageController.d.ts +6 -2
- package/dist/storage/index.d.ts +1 -0
- package/dist/storage/maintenance-keys.d.ts +17 -0
- package/dist/storage/maintenance-routes.d.ts +28 -5
- package/dist/storage/maintenance.d.ts +136 -4
- package/dist/storage/orphan-scans.d.ts +120 -0
- package/dist/storage/policies.d.ts +1 -1
- package/dist/storage/streams.d.ts +17 -0
- package/dist/storage/types.d.ts +26 -33
- package/dist/strings.es-B7QLnHh2.js +96 -0
- package/dist/strings.es-B7QLnHh2.js.map +1 -0
- package/dist/{upload-validation-Bgo626uY.js → upload-validation-CkkQGs-j.js} +40 -2
- package/dist/upload-validation-CkkQGs-j.js.map +1 -0
- package/dist/utils/load-failure.d.ts +9 -0
- package/package.json +5 -5
- package/dist/GCSStorageController-CRd9bFrc.js.map +0 -1
- package/dist/S3StorageController-D00EFa5P.js.map +0 -1
- package/dist/auth-Dkvo2tTJ.js.map +0 -1
- package/dist/auth_adapter-CIItCTc8.js +0 -21
- package/dist/auth_adapter-CIItCTc8.js.map +0 -1
- package/dist/backend-DTAOsLQc.js.map +0 -1
- package/dist/cron-loader-Dj6lA4HQ.js.map +0 -1
- package/dist/cron-scheduler-B04ACoUE.js.map +0 -1
- package/dist/cron-store-DkyfuLOH.js.map +0 -1
- package/dist/ddl-bootstrap-Ck20GSIX.js.map +0 -1
- package/dist/function-loader-KKDqTcIr.js.map +0 -1
- package/dist/history-recorder-B2rkuhuy.js.map +0 -1
- package/dist/history-store-DPofGVDp.js.map +0 -1
- package/dist/jobs-h1WRq3cp.js.map +0 -1
- package/dist/load-failure-L5hvfDoG.js.map +0 -1
- package/dist/offline-BrqCRgih-BtDB1ecy.js.map +0 -1
- package/dist/openapi-generator-BjHr6upl.js.map +0 -1
- package/dist/proxy-CH8Jsovg.js.map +0 -1
- package/dist/request-timeout-59crS-9u.js.map +0 -1
- package/dist/soft-delete-params-BmlVwecC.js.map +0 -1
- package/dist/sql-export-routes-DmB_uZ4l.js.map +0 -1
- package/dist/strings.es-BeZWAodn.js.map +0 -1
- package/dist/upload-validation-Bgo626uY.js.map +0 -1
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
import { createRequire as __rebaseCreateRequire } from "module";
|
|
2
|
-
import __rebaseProcess from "process";
|
|
3
|
-
globalThis.process ??= __rebaseProcess;
|
|
4
|
-
__rebaseCreateRequire(import.meta.url);
|
|
5
|
-
//#region ../types/src/types/auth_adapter.ts
|
|
6
|
-
/**
|
|
7
|
-
* The request header that asks for a data-plane request to run as another
|
|
8
|
-
* user, named by uid.
|
|
9
|
-
*
|
|
10
|
-
* The server honours it only on a signed-in administrator's own session —
|
|
11
|
-
* never on an API key or the service key — and only through an adapter that
|
|
12
|
-
* implements {@link AuthAdapter.resolveUser}. Everywhere else a request that
|
|
13
|
-
* carries it is refused, never run as its caller.
|
|
14
|
-
*
|
|
15
|
-
* @group Auth
|
|
16
|
-
*/
|
|
17
|
-
var IMPERSONATE_HEADER = "x-rebase-impersonate";
|
|
18
|
-
//#endregion
|
|
19
|
-
export { IMPERSONATE_HEADER as t };
|
|
20
|
-
|
|
21
|
-
//# sourceMappingURL=auth_adapter-CIItCTc8.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"auth_adapter-CIItCTc8.js","names":[],"sources":["../../types/src/types/auth_adapter.ts"],"sourcesContent":["/**\n * @module AuthAdapter\n *\n * Pluggable authentication abstraction for Rebase.\n *\n * An `AuthAdapter` decouples authentication from the database layer,\n * allowing users to bring their own auth system (Clerk, Auth0, or other\n * external providers) while keeping the Rebase admin frontend fully functional.\n *\n * @example Built-in auth (default — zero config change)\n * ```ts\n * initializeRebaseBackend({\n * auth: { jwtSecret: \"...\", google: { clientId: \"...\" } },\n * database: createPostgresAdapter({ ... }),\n * });\n * ```\n *\n * @example Custom auth\n * ```ts\n * import { createCustomAuthAdapter } from \"@rebasepro/server\";\n *\n * initializeRebaseBackend({\n * auth: createCustomAuthAdapter({\n * verifyRequest: async (req) => { ... },\n * }),\n * database: createPostgresAdapter({ ... }),\n * });\n * ```\n *\n * @group Auth\n */\n\n/**\n * A sub-app an adapter hands back for the framework to mount.\n *\n * Structural on purpose. This was `Hono<any, any, any>`, and that one\n * `import type { Hono } from \"hono\"` was the whole reason `@rebasepro/types`\n * peer-depended on hono — which npm and pnpm auto-install, so **every browser\n * app that installed `@rebasepro/client` got a 2.8 MB server framework in its\n * lockfile and its security scanners**, for a type used by two optional methods\n * that a browser app can never call.\n *\n * The shape is the same duck-type the function loader already validates at\n * runtime (`isHonoLike`: a `fetch` method and a `routes` array), and a real\n * `Hono` satisfies it — asserted in `auth_adapter.test.ts`, which does import\n * hono, because a structural type is only worth having if something proves the\n * real thing still fits.\n *\n * @group Auth\n */\nexport interface MountableRouter {\n /** Handle a request. Hono, Elysia and a hand-rolled router all have this. */\n fetch: (request: Request) => Response | Promise<Response>;\n /** The routes the sub-app declares. Only its presence is contractual. */\n routes: readonly unknown[];\n}\n\n// ─── Impersonation ───────────────────────────────────────────────────────────\n\n/**\n * The request header that asks for a data-plane request to run as another\n * user, named by uid.\n *\n * The server honours it only on a signed-in administrator's own session —\n * never on an API key or the service key — and only through an adapter that\n * implements {@link AuthAdapter.resolveUser}. Everywhere else a request that\n * carries it is refused, never run as its caller.\n *\n * @group Auth\n */\nexport const IMPERSONATE_HEADER = \"x-rebase-impersonate\";\n\n// ─── Authenticated User ──────────────────────────────────────────────────────\n\n/**\n * The normalized user object returned by `AuthAdapter.verifyRequest()`.\n *\n * Regardless of the auth provider, every request is resolved to this shape\n * so that downstream middleware (RLS scoping, route guards) can work uniformly.\n *\n * @group Auth\n */\nexport interface AuthenticatedUser {\n /** Unique user identifier (provider-specific). */\n uid: string;\n /** Primary email address. */\n email: string;\n /** Human-readable display name. */\n displayName?: string | null;\n /** Avatar URL. */\n photoUrl?: string | null;\n /** Role identifiers the user holds. */\n roles: string[];\n /**\n * Whether `roles` includes `admin`. Informational — every authorization\n * decision reads `roles` and the scopes they hold, so an adapter that\n * wants a user treated as an administrator gives them the `admin` role.\n */\n isAdmin: boolean;\n /**\n * Whether this session is a GUEST — anonymous sign-in rather than an\n * account.\n *\n * Optional, and absent means \"not a guest\", so an external adapter that\n * has no such concept keeps behaving exactly as it did. When present it\n * reaches the database as `rebase.is_anonymous()`, which is what lets a\n * policy say \"a signed-in person, not somebody who pressed Continue as\n * guest\" — two things that were the same principal inside every rule,\n * because anonymous sign-in mints a real user row with a real uid.\n */\n isAnonymous?: boolean;\n /** Raw bearer token from the request (for forwarding). */\n rawToken?: string;\n /** Extra claims/metadata from the auth provider. */\n claims?: Record<string, unknown>;\n /**\n * What this credential may do, when it is narrower than its person — set\n * for an API key. Absent means everything the user's roles hold\n * (`scopesForRoles`).\n */\n scopes?: string[];\n}\n\n// ─── Capabilities ────────────────────────────────────────────────────────────\n\n/**\n * Feature flags advertised by an auth adapter.\n *\n * The frontend reads these from `GET /api/auth/config` to dynamically\n * show/hide UI elements (login form, registration, password reset, etc.).\n *\n * @group Auth\n */\nexport interface AuthAdapterCapabilities {\n /**\n * Whether this adapter mounts its own `/auth/*` routes.\n *\n * - `true` for the built-in Rebase auth (login, register, refresh, etc.)\n * - `false` for external providers like Clerk or Auth0 that handle\n * auth flows outside of the Rebase backend.\n */\n hasBuiltInAuthRoutes: boolean;\n\n /** Supports email/password login. */\n emailPasswordLogin: boolean;\n /**\n * Whether self-registration is open **right now**.\n *\n * A runtime answer, not a static feature list: the built-in adapter also\n * reports `true` during the first-user bootstrap window (an empty user\n * table) and `false` the moment `disableSelfRegistration` is set. Whatever\n * this says, `POST /auth/register` does — both read the same predicate, so\n * the UI can never be sent to a form that can only 403.\n */\n registrationEnabled: boolean;\n /**\n * Supports the end-user password reset flow (emailing a reset link).\n *\n * This is about *self-service* reset, so it is typically tied to whether an\n * email service is configured. It says nothing about whether an admin can\n * reset someone else's password — see `adminPasswordReset`.\n */\n passwordReset: boolean;\n /**\n * Whether the adapter exposes `POST /admin/users/:uid/reset-password`,\n * letting an admin reset another user's password.\n *\n * Independent of `passwordReset`: the built-in adapter supports this even\n * with no email service configured (it returns a one-time temporary\n * password instead of sending a link). Adapters that mount their own admin\n * routes must set this to `true` only once that route actually exists —\n * the admin UI hides the \"Reset Password\" action when it is `false`.\n */\n adminPasswordReset: boolean;\n /** Supports session listing/revocation. */\n sessionManagement: boolean;\n /** Supports profile updates (display name, photo). */\n profileUpdate: boolean;\n /** Supports email verification. */\n emailVerification: boolean;\n /** Supports passwordless magic link login. */\n magicLink: boolean;\n /**\n * Supports passwordless sign-in with a six-digit code sent by email.\n *\n * Optional so that an external adapter written before this existed still\n * satisfies the interface; absent reads as \"no\", which is what an adapter\n * that has never heard of the flow means.\n */\n emailOtp?: boolean;\n /** Whether `POST /auth/anonymous` will mint a credential-less session. */\n anonymousLogin: boolean;\n /** List of enabled OAuth provider IDs (e.g. `[\"google\", \"github\"]`). */\n enabledProviders: string[];\n\n /**\n * For external auth (Clerk, Auth0, etc.): the URL where the user should\n * be redirected for login. The Rebase frontend will navigate here instead\n * of showing its own login form.\n */\n externalLoginUrl?: string;\n\n /**\n * True when no users exist yet — first-user bootstrap mode.\n * Only applicable for built-in auth.\n */\n needsSetup?: boolean;\n}\n\n/**\n * What `GET /api/auth/config` answers: the auth adapter's capabilities, plus\n * the optional features of the backend around it.\n *\n * The admin panel reads this document before anything else, so it is where\n * the panel learns that a feature is off, without first asking for that\n * feature and getting a refusal.\n *\n * @group Auth\n */\nexport interface AuthConfigDocument extends AuthAdapterCapabilities {\n /**\n * Whether this backend serves file storage. When it is `false`, no storage\n * backend is configured: `GET /storage/sources` lists nothing and every\n * other `/storage` route answers 501 `STORAGE_NOT_CONFIGURED`. Absent from\n * a backend that predates the field, so a client must ask\n * `GET /storage/sources` there.\n */\n storage?: boolean;\n}\n\n// ─── User Management ────────────────────────────────────────────────────────\n\n/**\n * Options for paginated user listing.\n * @group Auth\n */\nexport interface AuthUserListOptions {\n limit?: number;\n offset?: number;\n search?: string;\n orderBy?: string;\n orderDir?: \"asc\" | \"desc\";\n roleId?: string;\n}\n\n/**\n * Paginated user listing result.\n * @group Auth\n */\nexport interface AuthUserListResult {\n users: AuthUserData[];\n total: number;\n limit: number;\n offset: number;\n}\n\n/**\n * User data exposed by the auth adapter.\n * @group Auth\n */\nexport interface AuthUserData {\n id: string;\n email: string;\n displayName?: string | null;\n photoUrl?: string | null;\n emailVerified?: boolean;\n metadata?: Record<string, unknown>;\n createdAt?: Date;\n updatedAt?: Date;\n}\n\n/**\n * Data for creating a user.\n * @group Auth\n */\nexport interface AuthCreateUserData {\n email: string;\n password?: string;\n displayName?: string;\n photoUrl?: string;\n metadata?: Record<string, unknown>;\n /**\n * Store the address as verified: whoever creates the account named it\n * (an operator, an administrator), so nobody needs to prove it.\n */\n emailVerified?: boolean;\n}\n\n/**\n * User management operations for the admin panel.\n *\n * Optional — if not provided by the adapter, the user management UI is hidden.\n *\n * @group Auth\n */\nexport interface UserManagementAdapter {\n listUsers(options?: AuthUserListOptions): Promise<AuthUserListResult>;\n getUserById(id: string): Promise<AuthUserData | null>;\n createUser(data: AuthCreateUserData): Promise<AuthUserData>;\n updateUser(id: string, data: Partial<AuthCreateUserData>): Promise<AuthUserData | null>;\n deleteUser(id: string): Promise<void>;\n getUserRoles(uid: string): Promise<string[]>;\n setUserRoles(uid: string, roleIds: string[]): Promise<void>;\n}\n\n// ─── User Creation Lifecycle ─────────────────────────────────────────────────\n\n/**\n * Result of `AuthAdapter.prepareUserCreation()`.\n *\n * Contains the processed values ready for persistence and metadata\n * needed by the finalization step.\n *\n * @group Auth\n */\nexport interface UserCreationPrepareResult {\n /** Processed values to persist (passwordHash instead of raw password, etc.). */\n values: Record<string, unknown>;\n /** Cleartext password for post-save processing (email or admin display). */\n clearPassword?: string;\n /**\n * Whether the hook already handled the invitation (email, etc.). When\n * `true`, `finalizeUserCreation` is skipped and `clearPassword` is returned\n * to the admin as the temporary password.\n */\n hookHandledEmail: boolean;\n /** Whether an invitation was sent (only relevant when hookHandledEmail is true). */\n invitationSent: boolean;\n}\n\n/**\n * What the door creating a user knows about its caller, for\n * `AuthAdapter.prepareUserCreation()`.\n *\n * @group Auth\n */\nexport interface UserCreationOptions {\n /**\n * Whether the caller may waive the password policy with\n * `skipPasswordPolicy: true` in the body. The doors set it for an\n * administrator (the service key signs in as one) and for nobody else, so\n * an adapter that reads the flag is taking an administrator at their word —\n * an import of accounts whose passwords were set under another system's\n * rules. Absent, the flag waives nothing.\n */\n mayWaivePasswordPolicy?: boolean;\n}\n\n/**\n * What a create body for an auth collection may name beyond the collection's\n * own declared fields — see `AuthAdapter.describeUserCreationContract()`.\n *\n * @group Auth\n */\nexport interface UserCreationWriteContract {\n /**\n * Whether to check the body for fields neither the collection nor\n * {@link extraFields} declares. `false` skips the check entirely.\n */\n validate: boolean;\n /**\n * Credential and provider keys the adapter consumes itself, which the\n * collection therefore does not declare as columns. `password` is the\n * canonical one: `prepareUserCreation` hashes it into `passwordHash` and\n * deletes it before the row is ever built.\n */\n extraFields: string[];\n /**\n * Each body's `prepareUserCreation` touches nothing but its own result —\n * no hook, no email, no write — so a bulk create may prepare several at\n * once. The built-in adapter's path with no `onCreateUser`, no\n * `onAdminCreateUser` and the default `hashPassword` is: it hashes a\n * password and normalizes an email, and a 1,000-row bulk spent half a\n * minute hashing one password at a time. Leave it unset when a hook runs:\n * preparations then run one at a time, in the order the rows were given.\n */\n independent?: boolean;\n}\n\n/**\n * Result of `AuthAdapter.finalizeUserCreation()`.\n *\n * Returned to the REST API for inclusion in the response.\n *\n * @group Auth\n */\nexport interface UserCreationFinalizeResult {\n /** If set, returned to the admin in the API response. */\n temporaryPassword?: string;\n /** Whether an invitation email was sent. */\n invitationSent: boolean;\n /**\n * Whether an email service was configured but delivery failed, causing the\n * fallback to `temporaryPassword`. Absent when no email service is configured.\n */\n emailDeliveryFailed?: boolean;\n}\n\n// ─── Auth Response Transform ─────────────────────────────────────────────────\n\n/**\n * The auth response payload shape that flows through `transformAuthResponse`.\n *\n * For login, register, OAuth, anonymous, and magic-link flows the payload\n * contains both `user` and `tokens`. For refresh and MFA flows the payload\n * contains only `tokens` (no `user`).\n *\n * @group Auth\n */\nexport interface AuthResponsePayload {\n user?: {\n uid: string;\n email: string;\n displayName: string | null;\n photoURL: string | null;\n providerId?: string;\n isAnonymous?: boolean;\n emailVerified?: boolean;\n roles: string[];\n metadata: Record<string, unknown>;\n };\n tokens: {\n accessToken: string;\n refreshToken: string;\n accessTokenExpiresAt: number;\n /** Additional tokens injected by `transformAuthResponse`. */\n [key: string]: unknown;\n };\n}\n\n/**\n * Context passed to the `transformAuthResponse` hook.\n *\n * @group Auth\n */\nexport interface TransformAuthResponseContext {\n /** The authenticated user's ID. */\n uid: string;\n /** The auth method that triggered this response. */\n method: \"login\" | \"register\" | \"oauth\" | \"refresh\" | \"anonymous\" | \"magic-link\" | \"otp\" | \"mfa\";\n /** The raw HTTP request (for reading headers, IP, etc.). */\n request: Request;\n}\n\n// ─── Auth Adapter ────────────────────────────────────────────────────────────\n\n/**\n * Pluggable authentication adapter for Rebase.\n *\n * This is the **key interface** that decouples authentication from the\n * database layer. Each auth adapter knows how to:\n *\n * 1. Verify incoming HTTP requests (`verifyRequest`)\n * 2. Optionally manage users (for the admin panel)\n * 3. Optionally mount auth-specific routes (login, register, etc.)\n * 4. Advertise its capabilities so the frontend can adapt\n *\n * The built-in Rebase auth implements this interface internally.\n * External providers (Clerk, Auth0, or others) provide their own adapters.\n * Users with custom auth can use `createCustomAuthAdapter()` for a minimal setup.\n *\n * @group Auth\n */\nexport interface AuthAdapter {\n /**\n * Unique identifier for this auth adapter.\n *\n * @example \"rebase-builtin\", \"clerk\", \"auth0\", \"external-provider\", \"custom\"\n */\n readonly id: string;\n\n // ── Request Authentication ──────────────────────────────────────────\n\n /**\n * Verify an incoming request and extract the authenticated user.\n *\n * This replaces the hardcoded JWT verification in server's middleware.\n * Each adapter implements its own token verification strategy:\n * - Built-in: verify Rebase JWT\n * - Clerk: call Clerk's `verifyToken()`\n * - Auth0: validate Auth0 JWT with JWKS\n * - Custom: whatever logic the user provides\n *\n * @param request - The raw `Request` object (portable across Hono, Express, Fastify)\n * @returns The authenticated user, or `null` for unauthenticated requests.\n * Throw an error to reject the request with 401.\n */\n verifyRequest(request: Request): Promise<AuthenticatedUser | null>;\n\n /**\n * Verify a raw bearer token and extract the authenticated user.\n *\n * Used for **WebSocket authentication**, where there is no HTTP `Request`\n * object — only a token string sent over the socket.\n *\n * If not implemented, the default behavior synthesizes a minimal `Request`\n * with an `Authorization: Bearer <token>` header and delegates to\n * `verifyRequest()`. Adapters should override this if their token\n * verification logic doesn't depend on request headers/cookies.\n *\n * @param token - The raw bearer token string.\n * @returns The authenticated user, or `null` if the token is invalid.\n */\n verifyToken?(token: string): Promise<AuthenticatedUser | null>;\n\n /**\n * The identity a verified request from this account would carry right\n * now, with no credential involved: its uid, its roles as they are now,\n * its guest flag, and the custom claims a token minted for it now would\n * hold. `null` when no active account has this uid — none at all, or one\n * that is disabled.\n *\n * This is what lets an administrator run a request as another user (the\n * {@link IMPERSONATE_HEADER} header). The server calls it only after it\n * has decided the caller may do that, and it calls it for the caller too,\n * so the decision rests on the caller's roles as they are now rather than\n * on the ones their token claims.\n *\n * Optional. An adapter without it cannot be impersonated through, and a\n * request carrying the header is refused rather than run as its caller.\n */\n resolveUser?(uid: string): Promise<AuthenticatedUser | null>;\n\n // ── User Management (for admin panel) ────────────────────────────\n\n /**\n * User CRUD for the admin panel's user management UI.\n * Optional — if not provided, user management UI is hidden.\n */\n userManagement?: UserManagementAdapter;\n\n // ── Auth Routes ─────────────────────────────────────────────────────\n\n /**\n * Mount adapter-specific auth routes (login, register, refresh, etc.).\n *\n * - Built-in adapter: mounts `/auth/login`, `/auth/register`, etc.\n * - External adapter: typically returns `undefined` (auth is handled externally).\n * - Custom adapter: user mounts their own routes.\n *\n * The return type is the structural {@link MountableRouter} rather than\n * `Hono`, so this package needs no hono dependency. A real `Hono<HonoEnv>`\n * satisfies it, and implementations are free to use their own env.\n *\n * @returns A Hono sub-app with auth routes, or `undefined` to skip route mounting.\n */\n createAuthRoutes?(): MountableRouter | undefined;\n\n /**\n * Mount admin routes (e.g. password reset for users).\n *\n * @returns A Hono sub-app with admin routes, or `undefined` to skip.\n */\n createAdminRoutes?(): MountableRouter | undefined;\n\n // ── Feature Detection ───────────────────────────────────────────────\n\n /**\n * Advertise what this auth adapter supports.\n *\n * The frontend reads this from `GET /api/auth/config` to dynamically\n * show/hide UI elements. This is the bridge between backend capabilities\n * and the frontend's `AuthCapabilities` type.\n */\n getCapabilities(): AuthAdapterCapabilities | Promise<AuthAdapterCapabilities>;\n\n // ── Lifecycle ───────────────────────────────────────────────────────\n\n /**\n * Called during backend initialization.\n * Use for running migrations, creating tables, seeding initial data, etc.\n */\n initialize?(): Promise<void>;\n\n /**\n * Called during graceful shutdown.\n * Use for closing connections, flushing caches, etc.\n */\n destroy?(): Promise<void>;\n\n // ── Collection User Creation (for auth collections) ───────────────\n\n /**\n * Prepare values for creating a user via the auth collection's REST API.\n *\n * Called on POST to a collection with `auth: true`. Handles password\n * hashing, email normalization, and any collection/backend-level hooks.\n *\n * If not implemented, the collection saves values as-is (no password hashing).\n *\n * A chosen `password` is held to the password policy unless the body says\n * `skipPasswordPolicy: true` and `options.mayWaivePasswordPolicy` is set.\n *\n * @param values - Raw request body from the client.\n * @param collectionAuth - The parsed `AuthCollectionConfig` from the collection (if `auth` is an object).\n * @param options - What the door knows about its caller.\n * @returns Processed values ready for `driver.save()`, plus metadata for the post-save step.\n */\n prepareUserCreation?(\n values: Record<string, unknown>,\n collectionAuth?: unknown,\n options?: UserCreationOptions\n ): Promise<UserCreationPrepareResult>;\n\n /**\n * Describe what a create body for this auth collection is allowed to name,\n * so unknown-field validation can run on it.\n *\n * A signup body is not the collection's shape: it carries credential fields\n * like `password` that the users table never declares as columns, and\n * `prepareUserCreation` maps them onto real ones. Validating the raw body\n * against the collection alone would reject every legitimate signup — which\n * is why the check used to be skipped outright for auth collections. That\n * skip was total, so an undeclared field was silently dropped and the write\n * still returned 201, while the same typo on a normal collection was a 400.\n *\n * This narrows the exemption to the fields the adapter actually consumes.\n *\n * `validate: false` disables the check for this collection, and is the right\n * answer when a custom `onCreateUser` hook is configured: the body is then\n * the hook's contract, not the collection's, and this layer cannot know what\n * the hook accepts.\n *\n * If not implemented, validation is skipped — the pre-existing behaviour.\n *\n * @param collectionAuth - The parsed `AuthCollectionConfig` from the collection (if `auth` is an object).\n */\n describeUserCreationContract?(\n collectionAuth?: unknown\n ): UserCreationWriteContract;\n\n /**\n * Finalize a user creation after the entity has been persisted.\n *\n * Handles post-save work: sending invitation emails, generating\n * password-reset tokens, or falling back to returning a temporary password.\n *\n * Not called when `prepareUserCreation` reported `hookHandledEmail`. A\n * create hook then owns delivery, and the response carries the\n * `invitationSent` and `clearPassword` the prepare step returned. This\n * holds for both ways of creating a user: a `POST` to the auth collection\n * and `POST /admin/users`.\n *\n * @param entity - The persisted entity (id + values).\n * @param clearPassword - The cleartext password from the prepare step (if any).\n * @returns Metadata for the API response (temporary password, invitation status).\n */\n finalizeUserCreation?(\n entity: { id: string; values: Record<string, unknown> },\n clearPassword?: string\n ): Promise<UserCreationFinalizeResult>;\n\n // ── User Administration Through the Auth Collection ─────────────────\n\n /**\n * Check, and put in stored form, updates to rows of the auth collection\n * that arrive through the data API — `PATCH /<users>/:id`, `PATCH /bulk`,\n * `_batch`, the realtime socket.\n *\n * Those rows are the users, so an update to one is user administration,\n * and has to hold to what the admin user routes hold to: no update that\n * leaves the project without an administrator, and an email stored the\n * way sign-in looks it up. Throws to refuse; the updates are judged\n * together, so a bulk demotion of every admin is refused even though each\n * row alone would pass.\n *\n * If not implemented, the values are written as they arrived.\n *\n * @returns Each update's values, as they should be written, in order.\n */\n prepareUserUpdates?(\n updates: ReadonlyArray<{ uid: string; values: Record<string, unknown> }>\n ): Promise<Record<string, unknown>[]>;\n\n /**\n * Check a deletion of these users through the data API before any row goes,\n * and run the hooks that may veto it (`beforeUserDelete`). Throws to\n * refuse — for one that would leave the project without an administrator,\n * among others.\n *\n * If not implemented, the rows are deleted as any other.\n */\n prepareUserDeletions?(uids: readonly string[]): Promise<void>;\n\n /**\n * After those users' rows are deleted through the data API: end their\n * sessions and run the after-delete hooks (`afterUserDelete`).\n */\n finalizeUserDeletions?(uids: readonly string[]): Promise<void>;\n\n // ── Service Key (optional) ──────────────────────────────────────────\n\n /**\n * A static secret key for server-to-server / script authentication.\n *\n * When set, requests with `Authorization: Bearer <serviceKey>` bypass\n * normal token verification and are granted admin-level access.\n */\n serviceKey?: string;\n\n // ── Response Transform ───────────────────────────────────────────────\n\n /**\n * Transform the auth response before sending it to the client.\n *\n * Called after successful login, register, refresh, OAuth, anonymous,\n * magic-link, and MFA flows. The hook receives the fully-formed\n * response and returns a (potentially enriched) response.\n *\n * Use cases:\n * - Inject tokens from external auth systems (custom provider tokens, etc.)\n * - Add project-specific metadata to the response\n * - Enrich the user object with data from external sources\n *\n * The hook runs in the request path — keep it fast.\n * Heavy work should be offloaded to `onAuthenticated` (fire-and-forget).\n */\n transformAuthResponse?(\n response: AuthResponsePayload,\n context: TransformAuthResponseContext\n ): Promise<AuthResponsePayload>;\n}\n\n// ─── Custom Auth Adapter Options ─────────────────────────────────────────────\n\n/**\n * Options for creating a minimal custom auth adapter via `createCustomAuthAdapter()`.\n *\n * This is the simplest way to plug an existing auth system into Rebase.\n * Only `verifyRequest` is required — everything else is optional.\n *\n * @group Auth\n */\nexport interface CustomAuthAdapterOptions {\n /**\n * Verify an incoming request and return the authenticated user.\n * This is the only required method.\n */\n verifyRequest: (request: Request) => Promise<AuthenticatedUser | null>;\n\n /**\n * Verify a raw bearer token for WebSocket authentication.\n * Optional — if omitted, a synthetic `Request` is constructed and passed\n * to `verifyRequest`.\n */\n verifyToken?: (token: string) => Promise<AuthenticatedUser | null>;\n\n /** Optional user management for the admin panel. */\n userManagement?: UserManagementAdapter;\n\n /** Static service key for server-to-server auth. */\n serviceKey?: string;\n\n /** Override default capabilities. */\n capabilities?: Partial<AuthAdapterCapabilities>;\n\n /**\n * Transform the auth response before sending it to the client.\n * Same semantics as `AuthAdapter.transformAuthResponse`.\n */\n transformAuthResponse?: (\n response: AuthResponsePayload,\n context: TransformAuthResponseContext\n ) => Promise<AuthResponsePayload>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAsEA,IAAa,qBAAqB"}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"backend-DTAOsLQc.js","names":[],"sources":["../../types/src/types/backend.ts"],"sourcesContent":["import type { CollectionConfig, FilterValues, WhereFilterOp } from \"./collections\";\nimport type { CollectionCallbacks } from \"./entity_callbacks\";\nimport type { OrderByTuple } from \"./filter-operators\";\nimport type { LogicalCondition } from \"../controllers/data\";\nimport type { AuthAdapter } from \"./auth_adapter\";\nimport type { HistoryConfig } from \"../controllers/client\";\nimport type { ChannelBusSetting } from \"./channel_bus\";\nimport type { SchemaEditingAdmin } from \"./schema_editing\";\nimport type { AccessModel } from \"./scopes\";\n\n// =============================================================================\n// DATABASE CONNECTION INTERFACES\n// =============================================================================\n\n/**\n * Abstract database connection interface.\n * Represents a connection to any database system.\n */\nexport interface DatabaseConnection {\n /**\n * Type identifier for this database (e.g., 'postgres', 'mongodb', 'mysql')\n */\n readonly type: string;\n\n /**\n * Whether the connection is currently active\n */\n readonly isConnected?: boolean;\n\n /**\n * Close the database connection and release resources.\n */\n close?(): Promise<void>;\n}\n\n// =============================================================================\n// QUERY BUILDING INTERFACES\n// =============================================================================\n\n/**\n * A single filter condition for database queries\n */\nexport interface QueryFilter {\n field: string;\n operator: WhereFilterOp;\n value: unknown;\n}\n\n/**\n * Options for fetching a collection of entities\n */\nexport interface FetchCollectionOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n filter?: FilterValues<Extract<keyof M, string>>;\n /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */\n orderBy?: string | OrderByTuple[];\n order?: \"desc\" | \"asc\";\n limit?: number;\n offset?: number;\n startAfter?: unknown;\n searchString?: string;\n databaseId?: string;\n collection?: CollectionConfig;\n}\n\n/**\n * Options for searching entities\n */\nexport interface SearchOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n filter?: FilterValues<Extract<keyof M, string>>;\n /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */\n orderBy?: string | OrderByTuple[];\n order?: \"desc\" | \"asc\";\n limit?: number;\n databaseId?: string;\n collection?: CollectionConfig;\n}\n\n/**\n * Options for counting entities\n */\nexport interface CountOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n filter?: FilterValues<Extract<keyof M, string>>;\n /**\n * An `or(...)`/`and(...)` group, alongside `filter`.\n *\n * Counted as well as fetched, or `total` describes a different set of rows\n * from the one that was served — the same reason `filter` is here.\n */\n logical?: LogicalCondition;\n searchString?: string;\n databaseId?: string;\n}\n\n/**\n * Abstract condition builder interface.\n * Implementations translate Rebase filter conditions to database-specific queries.\n *\n * Note: This interface can be implemented as instance methods or as a class with static methods.\n * For static implementations (like DrizzleConditionBuilder), use the ConditionBuilderStatic type.\n *\n * @template T The type of condition returned by the builder (e.g., SQL for PostgreSQL, Filter<Document> for MongoDB)\n */\nexport interface ConditionBuilder<T = unknown> {\n /**\n * Build filter conditions from Rebase FilterValues\n */\n buildFilterConditions<M extends Record<string, unknown>>(\n filter: FilterValues<Extract<keyof M, string>>,\n collectionPath: string,\n ...args: unknown[]\n ): T[];\n\n /**\n * Build search conditions for text search.\n *\n * At most one condition comes back, already complete: callers OR what they\n * get, and OR is right across the searchable *fields* but wrong across the\n * *terms* of the search string — a person typing two words means both, and\n * the two halves of a name are two different fields. The empty array still\n * means \"nothing here can be searched\", which every caller reads as \"no\n * rows\".\n */\n buildSearchConditions(\n searchString: string,\n properties: Record<string, unknown>,\n ...args: unknown[]\n ): T[];\n\n /**\n * Combine multiple conditions with AND operator\n */\n combineConditionsWithAnd(conditions: T[]): T | undefined;\n\n /**\n * Combine multiple conditions with OR operator\n */\n combineConditionsWithOr(conditions: T[]): T | undefined;\n}\n\n/**\n * Static condition builder type for implementations using static methods.\n * Use this type when the class provides static methods rather than instance methods.\n *\n * @example\n * // DrizzleConditionBuilder satisfies this type\n * const builder: ConditionBuilderStatic<SQL> = DrizzleConditionBuilder;\n */\nexport type ConditionBuilderStatic<T = unknown> = {\n buildFilterConditions<M extends Record<string, unknown>>(\n filter: FilterValues<Extract<keyof M, string>>,\n ...args: unknown[]\n ): T[];\n buildSearchConditions(\n searchString: string,\n properties: Record<string, unknown>,\n ...args: unknown[]\n ): T[];\n combineConditionsWithAnd(conditions: T[]): T | undefined;\n combineConditionsWithOr(conditions: T[]): T | undefined;\n};\n\n// =============================================================================\n// ENTITY REPOSITORY INTERFACES\n// =============================================================================\n\n/**\n * Abstract entity repository interface.\n * Handles all CRUD operations for entities in the database.\n *\n * Implementations should handle:\n * - Entity serialization/deserialization\n * - Relation resolution\n * - ID generation and conversion\n */\nexport interface DataRepository {\n /**\n * Fetch a single entity by ID\n */\n fetchOne<M extends Record<string, unknown>>(\n collectionPath: string,\n id: string | number,\n databaseId?: string\n ): Promise<Record<string, unknown> | undefined>;\n\n /**\n * Fetch a collection of entities with optional filtering, ordering, and pagination\n */\n fetchCollection<M extends Record<string, unknown>>(\n collectionPath: string,\n options?: FetchCollectionOptions<M>\n ): Promise<Record<string, unknown>[]>;\n\n /**\n * Search entities by text\n */\n searchRows<M extends Record<string, unknown>>(\n collectionPath: string,\n searchString: string,\n options?: SearchOptions<M>\n ): Promise<Record<string, unknown>[]>;\n\n /**\n * Count entities in a collection\n */\n count<M extends Record<string, unknown>>(\n collectionPath: string,\n options?: CountOptions<M>\n ): Promise<number>;\n\n /**\n * Save a entity (create or update)\n */\n save<M extends Record<string, unknown>>(\n collectionPath: string,\n values: Partial<M>,\n id?: string | number,\n databaseId?: string\n ): Promise<Record<string, unknown>>;\n\n /**\n * Delete a entity by ID\n */\n delete(\n collectionPath: string,\n id: string | number,\n databaseId?: string\n ): Promise<void>;\n\n /**\n * Check if a field value is unique in a collection\n */\n checkUniqueField(\n collectionPath: string,\n fieldName: string,\n value: unknown,\n excludeEntityId?: string,\n databaseId?: string\n ): Promise<boolean>;\n\n}\n\n// =============================================================================\n// REALTIME INTERFACES\n// =============================================================================\n\n/**\n * Configuration for subscribing to a collection\n */\nexport interface CollectionSubscriptionConfig {\n clientId: string;\n path: string;\n filter?: unknown;\n /**\n * An `or(...)`/`and(...)` group, applied alongside `filter`.\n *\n * Declared here because a subscription is a query, and every field a query\n * has this one needs too. It was missing, so the type-checked boundary\n * dropped it: the client sent the group, nothing rejected it, and the\n * subscription re-fetched with the group gone — pushing every row the\n * caller's policies allowed rather than the ones they asked for. The same\n * defect `FetchCollectionProps.logical` documents, one layer up.\n */\n logical?: LogicalCondition;\n /**\n * Where the subscription's page starts. Missing for the same reason, with\n * a quieter symptom: a subscriber watching page two was pushed page one,\n * and a `collection_update` frame carries no window for it to notice with.\n */\n offset?: number;\n /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */\n orderBy?: string | OrderByTuple[];\n order?: \"desc\" | \"asc\";\n limit?: number;\n startAfter?: unknown;\n databaseId?: string;\n searchString?: string;\n /** Ask each row which declared search field matched. */\n searchExplain?: boolean;\n}\n\n/**\n * Configuration for subscribing to a single entity\n */\nexport interface SingleSubscriptionConfig {\n clientId: string;\n path: string;\n id: string | number;\n}\n\n/**\n * Opt-in retention for one set of broadcast channels.\n *\n * Retention is configured on the server and nowhere else. A channel is created\n * by whoever names it, so letting a client ask for its own history depth would\n * let any visitor commit the backend to unbounded storage; and presence-only or\n * notification-only channels — the overwhelming majority — must not pay for a\n * feature they never use. With no rules configured nothing is written, no table\n * is created, and broadcast behaves exactly as it did before history existed.\n */\nexport interface ChannelRetentionRule {\n /**\n * Channel name to match. Either exact (`\"doc:42\"`) or a trailing-`*` prefix\n * (`\"doc:*\"`). Deliberately not a full glob or RegExp: this decides what\n * gets written to disk, and a rule whose blast radius is not obvious at a\n * glance is the wrong shape for that.\n */\n match: string;\n /** Keep at most this many of the most recent messages per channel. */\n limit?: number;\n /**\n * Keep messages for at most this long. Accepts a millisecond count or a\n * short duration string (`\"30s\"`, `\"15m\"`, `\"24h\"`, `\"7d\"`).\n */\n ttl?: number | string;\n}\n\n/**\n * Server-side realtime options.\n *\n * The channel bus contract and its config live in `./channel_bus` so that a\n * transport shipped as its own package depends on the contract alone.\n */\nexport interface RealtimeChannelsConfig {\n /**\n * Retention rules, most specific first — the first match wins. Omitted or\n * empty means no channel retains anything.\n */\n channels?: ChannelRetentionRule[];\n /**\n * How channel broadcast and presence reach other backend instances.\n * Defaults to `{ type: \"memory\" }` — i.e. they don't.\n */\n bus?: ChannelBusSetting;\n /**\n * How many subscriptions one socket may hold; the next is refused with\n * `TOO_MANY_SUBSCRIPTIONS`. A positive whole number, checked at boot.\n * Defaults to 1000. `REALTIME_MAX_SUBSCRIPTIONS_PER_SOCKET` wins over it.\n */\n maxSubscriptionsPerSocket?: number;\n /**\n * How many sockets one user (one identity: a signed-in user, an API key's\n * user, an impersonated user) may hold open on one server instance. The\n * next one's `AUTHENTICATE` is refused with `TOO_MANY_SOCKETS` and the\n * socket closed with 4002; the SDK keeps retrying with backoff, so it gets\n * in once another closes. A positive whole number, checked at boot.\n * Unset (the default) is no ceiling. `REALTIME_MAX_SOCKETS_PER_USER` wins\n * over it.\n */\n maxSocketsPerUser?: number;\n /**\n * The longest a change waits for the refetch that delivers it, in ms. A\n * refetch waits for 300 ms without a change, and at most this long under a\n * steady stream of writes. Defaults to 1000. A positive whole number,\n * checked at boot. `REALTIME_REFETCH_MAX_WAIT_MS` wins over it.\n */\n refetchMaxWaitMs?: number;\n /**\n * How long a big list subscription's total may be reused before it is\n * counted again, in ms. Unset (the default), every frame counts. Frames\n * that reuse it carry `meta.totalAsOf`. `REALTIME_RECOUNT_INTERVAL_MS`\n * wins over it.\n */\n recountIntervalMs?: number;\n /**\n * The smallest last total at which {@link recountIntervalMs} applies;\n * smaller lists are counted on every frame. Defaults to 100 000.\n * `REALTIME_RECOUNT_MIN_ROWS` wins over it.\n */\n recountMinRows?: number;\n /**\n * How changes are captured for realtime. `auto` (the default) installs\n * database-level capture where the connection can and falls back to\n * announcing the API's own writes where it cannot; `trigger` asks for\n * capture and warns when it is refused; `wal` is `trigger` until WAL\n * streaming ships; `off` announces the API's own writes only.\n * `REALTIME_CDC` wins over it.\n */\n cdc?: \"auto\" | \"wal\" | \"trigger\" | \"off\";\n /**\n * The URL path the realtime socket accepts upgrades on. Defaults to the\n * one the server derives from where it is mounted — `/` for a server at\n * `/api`, which is where the SDK dials. Set it when clients dial elsewhere\n * (a `websocketUrl` with a path). See {@link RealtimeSocketOptions.path}.\n */\n path?: string;\n}\n\n/**\n * Abstract realtime provider interface.\n * Handles real-time subscriptions and notifications for entity changes.\n */\nexport interface RealtimeProvider {\n /**\n * Subscribe to collection changes.\n *\n * `onError` is called when a fetch behind the subscription fails, a\n * refetch after a change included, with the error as it was thrown. It is\n * not called for a fetch that newer rows have already overtaken, or after\n * the subscription is gone. Without it, a subscriber whose fetch failed\n * was told nothing and kept waiting for rows.\n */\n subscribeToCollection(\n subscriptionId: string,\n config: CollectionSubscriptionConfig,\n callback?: (rows: Record<string, unknown>[]) => void,\n onError?: (error: unknown) => void\n ): void;\n\n /**\n * Subscribe to single entity changes. `onError` as for\n * {@link RealtimeProvider.subscribeToCollection}.\n */\n subscribeToOne(\n subscriptionId: string,\n config: SingleSubscriptionConfig,\n callback?: (row: Record<string, unknown> | null) => void,\n onError?: (error: unknown) => void\n ): void;\n\n /**\n * Unsubscribe from a subscription\n */\n unsubscribe(subscriptionId: string): void;\n\n /**\n * Notify all relevant subscribers of a entity update\n */\n notifyUpdate(\n path: string,\n id: string,\n row: Record<string, unknown> | null,\n databaseId?: string\n ): Promise<void>;\n\n /**\n * Called when the HTTP server is ready and listening.\n * Useful for providers that need the server address for callbacks.\n */\n onServerReady?(serverInfo: { port: number; hostname?: string }): void;\n\n /**\n * Gracefully shut down the realtime provider.\n * Called during server shutdown to clean up resources.\n */\n destroy?(): Promise<void>;\n\n /**\n * Stop the internal LISTEN client (e.g., PostgreSQL LISTEN/NOTIFY).\n * Called during graceful shutdown before closing database connections.\n */\n stopListening?(): Promise<void>;\n\n /**\n * The long-lived connections realtime depends on, for `/health`. A change\n * feed that has gone quiet — a half-open LISTEN connection — loses every\n * external and cross-instance change while writes through this instance\n * still look live, so it is reported rather than inferred.\n */\n health?(): RealtimeListenerHealth[];\n}\n\n/**\n * One long-lived realtime connection, as `/health` reports it.\n * @group Backend\n */\nexport interface RealtimeListenerHealth {\n /** What it carries — `\"cdc\"`, `\"cross-instance\"`, `\"channel-bus\"`. */\n name: string;\n /** Listening on a connection that answered its last heartbeat. */\n connected: boolean;\n /** When (epoch ms) it went down, while it is down. */\n downSince?: number;\n}\n\n// =============================================================================\n// COLLECTION REGISTRY INTERFACES\n// =============================================================================\n\n/**\n * Abstract collection registry interface.\n * Manages registration and lookup of entity collections.\n */\nexport interface CollectionRegistryInterface {\n /**\n * Register a collection\n */\n register(collection: CollectionConfig): void;\n\n /**\n * Get a collection by its path\n */\n getCollectionByPath(path: string): CollectionConfig | undefined;\n\n /**\n * Get all registered collections\n */\n getCollections(): CollectionConfig[];\n\n /**\n * Get the currently registered global callbacks, if any.\n */\n getGlobalCallbacks(): any | undefined;\n\n /**\n * Take the global callbacks declared on `initializeRebaseBackend({ callbacks })`.\n *\n * A driver resolves callbacks from the registry it builds for itself, so\n * this is how the backend's global ones reach it: the coordinator hands\n * them over after `initializeDriver` returns. Optional so a registry for a\n * driver that runs no callbacks still type-checks, but a project that\n * declares global callbacks over a registry without it is refused at boot\n * — hooks that never run look exactly like hooks that passed.\n */\n setGlobalCallbacks?(callbacks: CollectionCallbacks): void;\n}\n\n// =============================================================================\n// DATA TRANSFORMER INTERFACES\n// =============================================================================\n\n/**\n * Abstract data transformer interface.\n * Handles serialization/deserialization between frontend and database formats.\n */\nexport interface DataTransformer {\n /**\n * Transform entity data for storage in the database\n */\n serializeToDatabase<M extends Record<string, unknown>>(\n entity: M,\n collection: CollectionConfig\n ): Record<string, unknown>;\n\n /**\n * Transform database data back to entity format\n */\n deserializeFromDatabase<M extends Record<string, unknown>>(\n data: Record<string, unknown>,\n collection: CollectionConfig\n ): Promise<M>;\n}\n\n// =============================================================================\n// DATABASE ADMIN — CAPABILITY-SPECIFIC INTERFACES (1.3)\n// =============================================================================\n\n/**\n * The table column a value of a {@link SqlScriptResult} was read from, as the\n * database itself reported it — not as the query's text suggests.\n *\n * @group Admin\n */\nexport interface SqlScriptColumnSource {\n schema: string;\n table: string;\n column: string;\n}\n\n/**\n * One column of a {@link SqlScriptResult}, in result order.\n *\n * @group Admin\n */\nexport interface SqlScriptColumn {\n /** The name the result gives it. Two columns of one result may share it. */\n name: string;\n /** Its type, as the database names it: `integer`, `text[]`, `timestamp with time zone`. */\n type?: string;\n /**\n * Where the database says the value came from: a plain reference to a\n * column of a table or view, through any number of subqueries.\n *\n * Absent for everything no stored row holds — an expression, a cast that\n * changes the type, a literal, an aggregate, a function's output, a\n * `UNION`.\n */\n source?: SqlScriptColumnSource;\n}\n\n/**\n * A table or view some column of a {@link SqlScriptResult} came from.\n *\n * @group Admin\n */\nexport interface SqlScriptTable {\n schema: string;\n table: string;\n /** What the relation is. Only a `table` or a `partitioned table` holds rows that can be updated by key. */\n kind: \"table\" | \"partitioned table\" | \"view\" | \"materialized view\" | \"foreign table\" | \"other\";\n /** Its primary key columns, in key order. Empty when it has none. */\n primaryKey: string[];\n /**\n * Other tables inherit this one (by `INHERITS`, not as partitions). A row\n * read from it may live in one of them, and a primary key is not unique\n * across them.\n */\n hasInheritors: boolean;\n}\n\n/**\n * Something the database said while a script ran: `there is no transaction in\n * progress` for a ROLLBACK with nothing to end, a `RAISE NOTICE`.\n *\n * @group Admin\n */\nexport interface SqlScriptNotice {\n severity: string;\n message: string;\n}\n\n/**\n * What a SQL script a person wrote returned. See {@link SQLAdmin.runSqlScript}.\n *\n * @group Admin\n */\nexport interface SqlScriptResult {\n /**\n * The last statement's rows, every value as the text the database wrote\n * for it and `null` for SQL NULL — so a value written back is the value\n * that was read, whatever its type. Keyed by column name: of two columns\n * that share a name, the row holds the last.\n */\n rows: Record<string, string | null>[];\n /** The last statement's columns, in order. */\n columns: SqlScriptColumn[];\n /** The tables and views {@link SqlScriptColumn.source} names. */\n tables: SqlScriptTable[];\n /** The last statement's command: `SELECT`, `UPDATE`, `CREATE TABLE` … */\n command?: string;\n /**\n * How many rows the last statement returned or changed, when its command\n * reports a count — or, for a {@link truncated} result, how many it\n * returned, of which {@link rows} holds the first.\n */\n rowCount?: number;\n /**\n * The last statement returned more than a run keeps, and {@link rows}\n * holds only its first rows. The Studio console's door keeps at most\n * 10,000 rows, or 32 Mi characters of values, of one result: a run that\n * held every row of a million-row table took the server down with it.\n */\n truncated?: boolean;\n /** What the database said while the script ran, in order. */\n notices: SqlScriptNotice[];\n /**\n * The database role the script ran as, when it asked for one — said by\n * the transport that ran it. The role asked for, unless the server has\n * role switching turned off (`DISABLE_DB_ROLE_SWITCHING`) and runs every\n * statement as the connection owner, who is named here instead.\n */\n effectiveRole?: string;\n}\n\n/**\n * A query's result being read a batch at a time — see `SQLAdmin.openSqlCursor`.\n *\n * @group Admin\n */\nexport interface SqlCursor {\n /** The result's column names, in order. */\n readonly columns: string[];\n /**\n * The next rows, each value the text the database wrote for it and `null`\n * for NULL — `null` once there are none left.\n */\n read(): Promise<(string | null)[][] | null>;\n /** End the read and give the session back. Safe to call more than once. */\n close(): Promise<void>;\n}\n\n/**\n * Administrative operations for SQL-based databases (PostgreSQL, MySQL, etc.).\n * Used by the SQL Editor, RLS Editor, and schema browser.\n *\n * @group Admin\n */\nexport interface SQLAdmin {\n /**\n * Execute raw SQL against the database.\n *\n * `isolateSession` runs it on a connection of its own and resets that\n * connection's session state — role, session authorization, settings —\n * before it is reused. For SQL a person wrote (the Studio editor), which\n * may `SET ROLE` and must not leave that on a pooled connection the\n * server's own queries use next.\n *\n * `maxResultBytes` refuses a result whose rows take more than that many\n * bytes, with an error whose `code` is `RESULT_TOO_LARGE`, rather than\n * return it — never a part of it. On a session of its own the read stops\n * there; elsewhere the rows are measured once read. The WebSocket\n * `EXECUTE_SQL` door sets it for every caller.\n */\n executeSql(sql: string, options?: { database?: string; role?: string; params?: unknown[]; isolateSession?: boolean; maxResultBytes?: number }): Promise<Record<string, unknown>[]>;\n\n /**\n * Run a script a person wrote — the Studio SQL console — and describe what\n * it returned.\n *\n * On a session of its own, reset afterwards, as `role` for every statement\n * of it. Values come back as the database's text, and each column says\n * which table column it was read from, when the database says so: what\n * the console needs to write a cell back to the row it came from and to\n * no other. A script that leaves a transaction open is refused, and the\n * transaction rolled back: nothing outlives the run to be committed or\n * rolled back by a later one.\n *\n * Aborting `signal` cancels the run: the statement in progress is stopped\n * (`pg_cancel_backend` on a Postgres server; the in-process development\n * database cannot be interrupted, and the run ends on its own), and the\n * promise rejects.\n */\n runSqlScript?(sql: string, options?: { database?: string; role?: string; signal?: AbortSignal }): Promise<SqlScriptResult>;\n\n /**\n * Read the whole result of ONE query a person wrote, a batch at a time —\n * the Studio SQL console's \"Download full result as CSV\", which the\n * console's 10,000-row cap would otherwise leave no way to get.\n *\n * Through a server-side cursor, in a read-only transaction, on a session\n * of its own, as `role`: a write is refused by the database, and a second\n * statement by the protocol. Each batch is read when the previous one has\n * been consumed, so memory holds one batch whatever the result's size;\n * every read runs under the session's `statement_timeout`. The session is\n * reset and returned when the cursor is closed — which the caller must do,\n * on success, failure or a reader that went away.\n */\n openSqlCursor?(sql: string, options?: { database?: string; role?: string; batchSize?: number }): Promise<SqlCursor>;\n\n /**\n * Fetch the available databases on the server.\n */\n fetchAvailableDatabases?(): Promise<string[]>;\n\n /**\n * Fetch the available *native PostgreSQL* database roles (from `pg_roles`).\n *\n * These are connection-level roles — what the SQL editor can `SET ROLE` to,\n * and what `SecurityRule.pgRoles` targets. They are NOT application roles;\n * for those use {@link fetchApplicationRoles}.\n */\n fetchAvailableRoles?(): Promise<string[]>;\n\n /**\n * Fetch the *application-level* roles in use in this project.\n *\n * These are the strings stored on the users table's `roles` column and\n * exposed to policies as `rebase.roles()` — what `SecurityRule.roles`\n * matches against. Distinct from {@link fetchAvailableRoles}; the two are\n * not interchangeable.\n */\n fetchApplicationRoles?(): Promise<string[]>;\n\n /**\n * Fetch the current database name.\n */\n fetchCurrentDatabase?(): Promise<string | undefined>;\n\n /**\n * Hold a `LISTEN` on `channel`, on a connection of its own that stays open\n * and comes back after a drop, and call `onNotify` with each payload — what\n * wakes the job worker when another process enqueues, instead of a poll\n * every two seconds.\n *\n * Resolves once listening, with the stop. Rejects when no such connection\n * can be had — an in-process database, a first connect that fails — so the\n * caller can fall back to polling. `onReconnect` is called each time a\n * dropped connection is listening again: whatever was sent meanwhile is\n * lost. `channel` must be a plain identifier.\n */\n listen?(\n channel: string,\n onNotify: (payload: string) => void,\n options?: { onReconnect?: () => void }\n ): Promise<() => Promise<void>>;\n}\n\n/**\n * Administrative operations for document-based databases (MongoDB, Firestore, etc.).\n * Used by future document administration tools.\n *\n * @group Admin\n */\nexport interface DocumentAdmin {\n /**\n * Execute an aggregation pipeline or equivalent query.\n */\n executeAggregate?(pipeline: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;\n\n /**\n * Fetch statistics for a collection (document count, size, etc.).\n */\n fetchCollectionStats?(collectionName: string): Promise<{ count: number; sizeBytes?: number }>;\n}\n\n/**\n * Administrative operations for schema management.\n * Shared across SQL and document databases.\n *\n * @group Admin\n */\nexport interface SchemaAdmin {\n /**\n * Fetch database tables/collections not yet mapped to a Rebase collection.\n */\n fetchUnmappedTables?(mappedPaths?: string[]): Promise<string[]>;\n\n /**\n * Fetch column/field metadata for a single table/collection.\n * The return type is generic — SQL backends return TableMetadata,\n * document backends may return a different shape.\n */\n fetchTableMetadata?(tableName: string): Promise<unknown>;\n}\n\n/**\n * Metadata for a database branch.\n * @group Admin\n */\nexport interface BranchInfo {\n /** Branch name (without prefix). */\n name: string;\n /**\n * The PostgreSQL database the branch is — what to connect to, and what to\n * name as the source when copying it. As the branch's record says, never\n * derived from `name` again.\n */\n database: string;\n /** The database this branch was created from. */\n parentDatabase: string;\n /** When the branch was created. */\n createdAt: Date;\n /** Size in bytes, if available from the server. */\n sizeBytes?: number;\n}\n\n/**\n * Administrative operations for database branching.\n * Allows creating isolated database copies for development/preview workflows.\n *\n * @group Admin\n */\nexport interface BranchAdmin {\n /** Create a new branch (database copy) from the current or specified source database. */\n createBranch(name: string, options?: { source?: string }): Promise<BranchInfo>;\n\n /** Delete a branch database. Cannot delete the main/default database. */\n deleteBranch(name: string): Promise<void>;\n\n /** List all branches (databases that were created via branching). */\n listBranches(): Promise<BranchInfo[]>;\n\n /** Get info about a specific branch. */\n getBranchInfo(name: string): Promise<BranchInfo | undefined>;\n}\n\n/**\n * Union type for all admin capabilities.\n * A backend may implement any combination of these interfaces.\n *\n * Use type guards (`isSQLAdmin`, `isDocumentAdmin`, `isSchemaAdmin`, `isBranchAdmin`)\n * to safely narrow the type before calling methods.\n *\n * @group Admin\n */\nexport type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin>\n & Partial<BranchAdmin> & Partial<SchemaEditingAdmin>;\n\n/**\n * Type guard: can this admin plan a live schema change?\n *\n * Planning is engine-specific — it renders DDL, a Drizzle schema and the\n * declarative SQL artifacts — so the implementation lives in the driver\n * package. The server detects the capability structurally, exactly as it does\n * for SQL, rather than importing an engine it is supposed to know nothing\n * about.\n *\n * @group Admin\n */\nexport function isSchemaEditingAdmin(admin: DatabaseAdmin | undefined): admin is SchemaEditingAdmin {\n return !!admin && typeof (admin as SchemaEditingAdmin).planSchemaChange === \"function\";\n}\n\n/**\n * Type guard: does this admin support SQL operations?\n * @group Admin\n */\nexport function isSQLAdmin(admin: DatabaseAdmin | undefined): admin is SQLAdmin {\n return !!admin && typeof (admin as SQLAdmin).executeSql === \"function\";\n}\n\n/**\n * Type guard: does this admin support document operations?\n * @group Admin\n */\nexport function isDocumentAdmin(admin: DatabaseAdmin | undefined): admin is DocumentAdmin {\n return !!admin && (\n typeof (admin as DocumentAdmin).executeAggregate === \"function\" ||\n typeof (admin as DocumentAdmin).fetchCollectionStats === \"function\"\n );\n}\n\n/**\n * Type guard: does this admin support schema management?\n * @group Admin\n */\nexport function isSchemaAdmin(admin: DatabaseAdmin | undefined): admin is SchemaAdmin {\n return !!admin && (\n typeof (admin as SchemaAdmin).fetchUnmappedTables === \"function\" ||\n typeof (admin as SchemaAdmin).fetchTableMetadata === \"function\"\n );\n}\n\n/**\n * Type guard: does this admin support database branching?\n * @group Admin\n */\nexport function isBranchAdmin(admin: DatabaseAdmin | undefined): admin is BranchAdmin {\n return !!admin && typeof (admin as BranchAdmin).createBranch === \"function\";\n}\n\n// =============================================================================\n// LIFECYCLE INTERFACES (1.4)\n// =============================================================================\n\n/**\n * Health check result returned by `healthCheck()`.\n * @group Lifecycle\n */\nexport interface HealthCheckResult {\n /** Whether the backend is healthy and able to serve requests. */\n healthy: boolean;\n /** Round-trip latency to the database in milliseconds. */\n latencyMs: number;\n /** Optional details (e.g., pool stats, replication lag). */\n details?: Record<string, unknown>;\n}\n\n/**\n * Lifecycle contract for backend components that hold resources\n * (database connections, WebSocket pools, timers, etc.).\n *\n * All methods are optional — simple backends (e.g., in-memory) can skip them.\n * @group Lifecycle\n */\nexport interface BackendLifecycle {\n /**\n * Initialize the backend: open connections, run migrations, seed data.\n * Called once during startup. Idempotent.\n */\n initialize?(): Promise<void>;\n\n /**\n * Check whether the backend is healthy and reachable.\n * Should be fast (< 1 s) and safe to call frequently.\n */\n healthCheck?(): Promise<HealthCheckResult>;\n\n /**\n * Gracefully shut down: close connections, flush buffers, cancel timers.\n * After calling `destroy()`, no other methods should be called.\n */\n destroy?(): Promise<void>;\n}\n\n// =============================================================================\n// BACKEND FACTORY INTERFACES\n// =============================================================================\n\n/**\n * Configuration for creating a database backend\n */\nexport interface BackendConfig {\n /**\n * Type of database backend\n */\n type: string;\n\n /**\n * Database connection (implementation-specific)\n */\n connection: unknown;\n\n /**\n * Schema definition (implementation-specific, e.g., Drizzle schema for PostgreSQL)\n */\n schema?: unknown;\n}\n\n/**\n * A complete backend instance with all required services.\n *\n * Now includes optional lifecycle management and admin capabilities.\n */\nexport interface BackendInstance extends BackendLifecycle {\n /**\n * Entity repository for CRUD operations\n */\n entityRepository: DataRepository;\n\n /**\n * Realtime provider for subscriptions\n */\n realtimeProvider: RealtimeProvider;\n\n /**\n * Collection registry\n */\n collectionRegistry: CollectionRegistryInterface;\n\n /**\n * The underlying database connection\n */\n connection: DatabaseConnection;\n\n /**\n * Administrative operations (SQL, schema, documents).\n * What's available depends on the backend type — use type guards\n * (`isSQLAdmin`, `isSchemaAdmin`, etc.) to narrow.\n */\n admin?: DatabaseAdmin;\n}\n\n/**\n * Factory function type for creating backend instances\n */\nexport type BackendFactory<TConfig extends BackendConfig = BackendConfig> =\n (config: TConfig) => BackendInstance;\n\n// =============================================================================\n// BACKEND BOOTSTRAPPER (1.2)\n// =============================================================================\n\n/**\n * A caller of the data API as its rate limiter buckets one outside an HTTP\n * request: a realtime socket's frame, counted in the same bucket the same\n * person's HTTP requests are.\n * @group Backend\n */\nexport interface DataRateLimitCaller {\n /**\n * The signed-in user's uid. Absent, or the anonymous principal, buckets\n * the caller by address at the anonymous allowance.\n */\n uid?: string;\n /**\n * The API key the connection authenticated with. Its frames count in the\n * key's own bucket at the key's own `rate_limit`, the bucket its HTTP\n * requests count in, rather than as `uid`.\n */\n apiKey?: { id: string; rate_limit: number | null };\n /**\n * A header of the request that opened the connection, by lower-case name:\n * the proxy headers an address is read from when proxies are declared.\n */\n header(name: string): string | undefined;\n /** The address the connection comes from. */\n socketAddress?: string;\n}\n\n/**\n * What the realtime socket shares with the HTTP data API: its request limits,\n * so a frame carries the ones an HTTP request to the same rows does, and its\n * API-key verification, so a key means the same thing on both.\n * @group Backend\n */\nexport interface RealtimeSocketOptions {\n /**\n * Verify an `rk_` API key presented to `AUTHENTICATE`: the identity it acts\n * as and the scopes it holds, or why it does not authenticate. Absent when\n * the deployment has no API-key store, and then keys cannot authenticate\n * the socket.\n */\n resolveApiKey?: (token: string) => Promise<{\n uid: string;\n roles: string[];\n scopes: string[];\n /** The key itself: its id and `rate_limit` decide which rate-limit bucket its frames count in. */\n apiKey?: { id: string; rate_limit: number | null };\n } | { message: string }>;\n /**\n * Verify a session token presented to `AUTHENTICATE` with the backend's own\n * keys, when the socket has no auth adapter to ask: who it names, or null\n * when it does not verify. The server passes its backend's; absent, the\n * driver falls back to the process default.\n */\n verifyAccessToken?: (token: string) => Promise<{\n uid: string;\n roles?: string[];\n isAnonymous?: boolean;\n claims?: Record<string, unknown>;\n } | null>;\n /**\n * The backend's access model — what a session's roles hold on the socket's\n * admin frames. The server passes its backend's; absent, the driver falls\n * back to the process default.\n */\n accessModel?: AccessModel;\n /**\n * The largest frame accepted, in bytes — the data API's body limit. `0` or\n * less for none. Defaults to the server's default body limit.\n */\n maxPayload?: number;\n /**\n * Count one data request from `caller` in the data API's per-caller\n * buckets and say whether it is allowed; `null` for a caller who is not\n * limited. Absent when the deployment has rate limiting off.\n */\n dataRateLimit?: (caller: DataRateLimitCaller) => Promise<{ allowed: boolean; retryAfterMs: number } | null>;\n /**\n * How often a socket that only listens has its identity re-read, in ms\n * (default 30 000). A socket that sends frames is re-checked before each\n * one; this bounds how long a subscription keeps receiving rows as an\n * identity that has since signed out, been revoked, demoted or deleted.\n */\n identityRecheckIntervalMs?: number;\n /**\n * How often a socket that asked for heartbeats (`?rebase_caps=heartbeat`)\n * is sent one, in ms (default 30 000). The SDK redials after two missed.\n */\n heartbeatIntervalMs?: number;\n /**\n * How many sockets one identity may hold open on this server; the next\n * one's `AUTHENTICATE` is refused with `TOO_MANY_SOCKETS` and the socket\n * closed (4002). Unset for no ceiling. See `realtime.maxSocketsPerUser`.\n */\n maxSocketsPerUser?: number;\n /**\n * The URL path the socket accepts upgrades on (default `/`). The SDK dials\n * its `baseUrl` with no extra segment, so for a server mounted at `/api`\n * this is `/`, and for one at `/app/api` it is `/app`. A trailing `/` is\n * ignored, and so is the query string.\n *\n * An upgrade to any other path is not this socket's: it is left untouched\n * for another `upgrade` listener on the same `http.Server` — a host app's\n * own WebSocket server — or, when the socket's listener is the only one,\n * answered `404` and closed, so the client is not left hanging.\n */\n path?: string;\n}\n\n/**\n * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.\n *\n * Instead of hard-coding Postgres setup into `initializeRebaseBackend()`,\n * each database backend provides its own bootstrapper that knows how to:\n * - Create the DataDriver from a config object\n * - Optionally initialize auth tables\n * - Optionally create a realtime service\n * - Mount driver-specific API routes\n *\n * The main `initializeRebaseBackend()` becomes a **coordinator** that iterates\n * registered bootstrappers, calls their hooks, and wires the results together.\n *\n * @group Backend\n *\n * @example\n * ```typescript\n * // Third-party MySQL bootstrapper\n * const mysqlBootstrapper: BackendBootstrapper = {\n * type: \"mysql\",\n * initializeDriver: async (config) => new MySQLDataDriver(config.connection),\n * initializeRealtime: async (config) => new MySQLChangeStreamRealtime(config.connection),\n * };\n *\n * initializeRebaseBackend({\n * ...config,\n * bootstrappers: [postgresBootstrapper, mysqlBootstrapper]\n * });\n * ```\n */\nexport interface BackendBootstrapper {\n /**\n * Which driver type this bootstrapper handles.\n * Must match the `type` field on the driver config object\n * (e.g., `\"postgres\"`, `\"mongodb\"`, `\"mysql\"`).\n */\n type: string;\n\n /**\n * Unique identifier for this bootstrapper instance.\n * Used to register the driver in the driver registry.\n * Defaults to `type` if not set.\n */\n id?: string;\n\n /**\n * Whether this bootstrapper provides the default driver.\n * When true, the coordinator uses this driver as the primary one.\n */\n isDefault?: boolean;\n\n /**\n * Run database migrations for this driver.\n * Called by the coordinator after all drivers are initialized.\n */\n runMigrations?(config: unknown, driverResult: InitializedDriver): Promise<void>;\n\n /**\n * Create a DataDriver from the given config.\n * This is the only **required** method.\n */\n initializeDriver(config: unknown): Promise<InitializedDriver>;\n\n /**\n * Initialize auth tables / services if this driver supports them.\n * Return undefined if auth is not supported by this backend.\n */\n initializeAuth?(config: unknown, driverResult: InitializedDriver): Promise<BootstrappedAuth | undefined>;\n\n /**\n * Initialize history tables / services if this driver supports them.\n * Return undefined if history is not supported by this backend.\n */\n initializeHistory?(config: HistoryConfig, driverResult: InitializedDriver): Promise<{ historyService: unknown } | undefined>;\n\n /**\n * Create a realtime provider for this driver.\n * Return undefined if the driver does not support realtime.\n */\n initializeRealtime?(config: unknown, driverResult: InitializedDriver): Promise<RealtimeProvider | undefined>;\n\n /**\n * Never called: the server mounts no route on a bootstrapper's behalf. A\n * driver that needs HTTP routes exports a route factory, and the app\n * mounts it where it chooses.\n *\n * @deprecated Never called. Will be removed in a future release.\n */\n mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;\n\n /**\n * Return admin capabilities for this driver.\n */\n getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;\n\n /**\n * Ask the database whether it is there, before anything else touches it.\n *\n * Boot's first database call is not `initializeDriver` — it is the schema\n * provisioning that runs ahead of it, and a driver's connection diagnosis\n * therefore never got the chance to run. A stopped database produced\n * `Failed query: [redacted]` and a stack through drizzle internals: no host,\n * no port, no `ECONNREFUSED`, and no hint about starting the thing.\n *\n * Implementations MUST issue the cheapest round trip they have (`SELECT 1`),\n * MUST throw an error whose message names the host, the port and the\n * driver's own reason, and MAY log a fuller diagnosis first. They MUST NOT\n * throw for a reachable database that merely answered something unexpected —\n * the caller treats a throw as fatal.\n *\n * `driverResult` is optional for the same reason as\n * {@link ensureCollectionSchema}: this runs before `initializeDriver`, so an\n * adapter that was constructed with its own connection has to fall back to\n * it.\n */\n verifyConnection?(driverResult?: InitializedDriver): Promise<void>;\n\n /**\n * Bring the database's collection tables up to date, additively.\n *\n * Optional because it is only meaningful for schema-ful drivers. A managed\n * runtime boots a compiled project against a database it has never seen; auth\n * tables are ensured on boot but collection tables were created by nothing,\n * so every data request answered 500 on a missing relation. The CLI's `db\n * push` cannot fill the gap — it needs Atlas, and the runtime image ships no\n * CLI.\n *\n * Implementations MUST be additive-only: create missing tables, columns and\n * enum types, and never drop, narrow or rewrite anything. This runs\n * unattended against live customer data with nobody reading a diff, so the\n * destructive half stays a deliberate migration.\n *\n * `driverResult` is optional: this runs before `initializeDriver`, and only\n * the bundle path has a pre-init stand-in to pass. An adapter built by an\n * application already holds its own connection and MUST use it when this is\n * `undefined` — dereferencing it unconditionally works for managed tenants\n * and breaks every app that builds its own adapter.\n */\n ensureCollectionSchema?(\n collections: unknown[],\n driverResult?: InitializedDriver,\n log?: (message: string) => void\n ): Promise<{ applied: number }>;\n\n /**\n * Apply the collections' row-level-security policies, additively and\n * idempotently — the companion to {@link ensureCollectionSchema}.\n *\n * That method creates the tables; a table with RLS disabled and no policies\n * is not servable, because authenticated requests run as a restricted role:\n * a read with no `SELECT` policy returns nothing (a public collection\n * answers 401) and a write with no `INSERT`/`UPDATE` policy is denied. The\n * `db push` CLI applies these from the same collections, but it cannot reach\n * a managed tenant's in-cluster database — the runtime, already connected,\n * is the only thing that can.\n *\n * MUST be idempotent (re-run on every boot) and MUST NOT be destructive.\n * Runs after auth initialization, because the generated policies call the\n * `auth.*` helper functions and `CREATE POLICY` validates they exist.\n */\n ensureCollectionPolicies?(\n collections: unknown[],\n driverResult?: InitializedDriver,\n log?: (message: string) => void\n ): Promise<{ applied: number }>;\n\n /**\n * Create the RLS helper functions on this source's database. See\n * `DatabaseAdapter.ensureRlsRuntime`; needed on every source that is not\n * the default, whose helpers arrive with the auth tables.\n */\n ensureRlsRuntime?(driverResult?: InitializedDriver): Promise<void>;\n\n /**\n * Re-check, after the schema exists, that requests will actually be\n * constrained by the database's own authorization.\n *\n * A driver that isolates user requests by switching to a restricted role has\n * to decide at connect time whether the switch is needed — and on a fresh\n * database that question is asked before there is anything to answer with.\n * The process then creates the schema, becomes its owner, and an owner is\n * exempt from the policies on what it owns. So the answer that was true when\n * the driver initialized can be false by the time it serves a request.\n *\n * This is where a driver asks again. It runs once, after collection tables,\n * auth tables and policies are all in place, and it MUST fail rather than\n * serve when the answer changed and cannot be acted on: booting anyway\n * produces exactly the unenforced server this exists to prevent.\n *\n * Optional, because it is only meaningful for drivers whose isolation\n * depends on state the schema affects. A driver with nothing to re-check\n * omits it.\n */\n finalizeSecurityPosture?(driverResult: InitializedDriver): Promise<void>;\n\n /**\n * Read the collections schema version this database was last provisioned\n * from, or `null` when nothing has ever stamped it.\n *\n * The companion to {@link stampCollectionsSchemaVersion}: one process writes\n * what it applied, every other process compares itself to it. This is what\n * lets a split deployment — several processes over one database, only one of\n * which provisions — notice that a unit is serving against a schema it was\n * not built for. That failure is otherwise silent in both directions: a\n * column that does not exist is a SQL error on one route, and a policy that\n * was never applied is a 200 with no rows.\n *\n * `null` is not an error and MUST NOT be treated as one — every database\n * provisioned before the stamp existed reads this way, and so does every\n * fresh one until its first provisioning boot finishes.\n */\n readCollectionsSchemaVersion?(\n driverResult?: InitializedDriver\n ): Promise<string | null>;\n\n /**\n * Record the collections schema version this process just applied.\n *\n * Called only by the process that provisions, and only after both\n * {@link ensureCollectionSchema} and {@link ensureCollectionPolicies} have\n * run — a stamp written before the policies would claim a schema that is\n * only half in place, and the half that is missing is the one that fails\n * without an error.\n */\n stampCollectionsSchemaVersion?(\n version: string,\n driverResult?: InitializedDriver\n ): Promise<void>;\n\n /**\n * Initialize WebSocket server for realtime operations.\n */\n initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import(\"../controllers/data_driver\").DataDriver, config?: unknown, authAdapter?: AuthAdapter, limits?: RealtimeSocketOptions): Promise<void> | void;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeDriver()`.\n * @group Backend\n */\nexport interface InitializedDriver {\n /** The DataDriver instance, ready for use. */\n driver: import(\"../controllers/data_driver\").DataDriver;\n\n /** The realtime service, if the driver created one during init. */\n realtimeProvider?: RealtimeProvider;\n\n /** A collection registry to register schema / tables into. */\n collectionRegistry?: CollectionRegistryInterface;\n\n /**\n * Collections the driver derived from the live database schema.\n *\n * Set by drivers that introspect in `baas` mode; the server serves these\n * instead of collections loaded from config files.\n */\n collections?: import(\"./collections\").CollectionConfig[];\n\n /**\n * Tables the driver found while deriving {@link collections} and did not\n * serve, because row-level security is disabled on them and so they have\n * no authorization model (`baas.unprotectedTables` left at `\"exclude\"`).\n *\n * The server names them when it has nothing to serve: \"the database has\n * no tables\" is untrue of a database whose tables were all skipped.\n */\n unprotectedTables?: { schema: string; table: string }[];\n\n /** The underlying database connection (for lifecycle management). */\n connection?: DatabaseConnection;\n\n /**\n * Opaque handle that the bootstrapper can use in subsequent hooks\n * (e.g., `initializeAuth`, `getAdmin`) to access driver internals.\n * Not used by the coordinator.\n */\n internals?: unknown;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeAuth()`.\n * @group Backend\n */\nexport interface BootstrappedAuth {\n /** User management service. */\n userService: unknown;\n /** Email service (optional). */\n emailService?: unknown;\n /** Combined Auth Repository for unified token and user management. */\n authRepository?: unknown;\n /**\n * Whether the auth schema in the database is one this runtime can serve.\n *\n * Folded into `healthCheck()` so a schema mismatch shows up as a degraded\n * health response. Without it, a server whose auth is entirely broken still\n * reports healthy — the database connection it probes is fine, and the\n * mismatch is only discovered one failed login at a time.\n */\n schemaHealthCheck?(): Promise<AuthSchemaHealth>;\n}\n\n/**\n * Result of {@link BootstrappedAuth.schemaHealthCheck}.\n * @group Lifecycle\n */\nexport interface AuthSchemaHealth {\n /** False when this runtime cannot be trusted to serve auth against this database. */\n healthy: boolean;\n /** Human-readable descriptions of each mismatch found. Empty when healthy. */\n problems: string[];\n /** Auth schema version recorded in the database, when it records one. */\n databaseVersion?: number | null;\n /** Auth schema version this runtime expects. */\n runtimeVersion?: number;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA82BA,SAAgB,qBAAqB,OAA+D;CAChG,OAAO,CAAC,CAAC,SAAS,OAAQ,MAA6B,qBAAqB;AAChF;;;;;AAMA,SAAgB,WAAW,OAAqD;CAC5E,OAAO,CAAC,CAAC,SAAS,OAAQ,MAAmB,eAAe;AAChE"}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"cron-loader-Dj6lA4HQ.js","names":[],"sources":["../src/cron/cron-loader.ts"],"sourcesContent":["import * as fs from \"fs\";\nimport * as path from \"path\";\nimport { pathToFileURL } from \"url\";\nimport { declareCron, type CronJobDefinition, type CronResourceOptions } from \"@rebasepro/types\";\nimport { logger } from \"../utils/logger.js\";\nimport { nativeDynamicImport, type ModuleImporter } from \"../utils/dynamic-import.js\";\nimport { describeLoadFailure, SYNTAX_ERROR_ADVICE } from \"../utils/load-failure.js\";\nimport { warnDeprecated } from \"@rebasepro/common\";\nimport type { LoadDirectoryOptions } from \"../functions/function-loader.js\";\n\n/**\n * Cron jobs as values: the job id, to its definition.\n *\n * `crons: { \"nightly-report\": nightlyReport }` schedules `nightlyReport` as the\n * job `nightly-report` — the same thing a file named `crons/nightly-report.ts`\n * does. {@link loadCrons} returns exactly this shape, so\n * `crons: await loadCrons(dir)` and `cronsDir: dir` schedule the same jobs.\n *\n * A value is what the author wrote — `defineCron({...})` — with no defaults\n * filled in. The scheduler fills them in when it registers the job.\n */\nexport type CronsRecord = Record<string, CronJobDefinition>;\n\n/** A job as the scheduler registers it: its id, and its definition with defaults filled in. */\nexport interface LoadedCronJob {\n /** Job ID derived from filename (e.g. \"cleanup-sessions\"). */\n id: string;\n /** The full definition. */\n definition: CronJobDefinition;\n}\n\n/** {@link loadCronJobsWithDiagnostics}' answer: what loaded, and what did not. */\nexport interface LoadedCronJobs {\n jobs: LoadedCronJob[];\n /** One entry per file that will NOT be scheduled, with the reason. */\n problems: string[];\n}\n\n/**\n * Load the cron jobs in a directory, as values.\n *\n * Each file default-exports a `CronJobDefinition` — `defineCron({...})`. The\n * filename without its extension is the record key, which is the job id:\n * `crons/cleanup-sessions.ts` → `{ \"cleanup-sessions\": definition }`.\n *\n * Loading declares nothing: the definitions come back exactly as written, and\n * whoever uses them decides what they are for — a backend schedules them, the\n * build's derive step records them in the resource graph ({@link declareCrons}).\n *\n * Never throws for a bad file: it is skipped, logged, and passed to\n * `options.onSkip`.\n *\n * @example\n * ```ts\n * const crons = await loadCrons(path.resolve(\"crons\"));\n * const backend = await createRebaseBackend({ database, crons, provision: true });\n * ```\n */\nexport async function loadCrons(directory: string, options: LoadDirectoryOptions = {}): Promise<CronsRecord> {\n const { crons, problems } = await readCronsDirectory(directory, options.importModule);\n if (options.onSkip) for (const problem of problems) options.onSkip(problem);\n return crons;\n}\n\n/**\n * Record each cron in the project's resource graph — what `rebase resources`\n * lists and a host reads to know a schedule exists, without running it.\n *\n * Keyed by the same id the scheduler, the routes and the Studio use, and built\n * from the definitions as written: a default the scheduler fills in\n * (`enabled: true`, `timeoutSeconds: 300`) is this process's, not something the\n * author declared.\n */\nexport function declareCrons(crons: CronsRecord): void {\n for (const [id, definition] of Object.entries(crons)) {\n declareCron(id, cronResourceOptions(definition));\n }\n}\n\n/**\n * The jobs a scheduler registers, from cron values: the definitions with this\n * process's defaults filled in.\n *\n * Spread first, then normalise. Rebuilding the object field by field dropped\n * `catchUpWindowSeconds` once — and since this is the path every job takes to\n * the scheduler, catch-up never ran for any job authored the documented way. A\n * field added to `CronJobDefinition` tomorrow would be dropped the same way.\n *\n * @throws when a value has no `schedule` or no `handler`. A file like that is\n * skipped by the loader with a reason; a value handed over in code is refused,\n * because the caller is right there to fix it.\n */\nexport function cronJobsFrom(crons: CronsRecord): LoadedCronJob[] {\n return Object.entries(crons).map(([id, definition]) => {\n const def = definition as Partial<CronJobDefinition> | undefined;\n if (!def || typeof def.schedule !== \"string\" || typeof def.handler !== \"function\") {\n throw new Error(\n `crons[\"${id}\"] is not a cron job: it needs a \\`schedule\\` string and a \\`handler\\` function. ` +\n \"Author it with `defineCron({ schedule, handler })`.\"\n );\n }\n return {\n id,\n definition: {\n ...def,\n schedule: def.schedule,\n name: def.name || id,\n enabled: def.enabled !== false,\n // `??`, not `||`: zero and NaN are values the author wrote, and\n // the scheduler refuses both by name (they end up under\n // `rejected`). `|| 300` swallowed them, so a job written with\n // `0` meaning \"no limit\" ran with five minutes and was listed as\n // healthy. `Infinity` is \"none\".\n timeoutSeconds: def.timeoutSeconds ?? 300,\n handler: def.handler\n }\n };\n });\n}\n\n/**\n * @deprecated Use `loadCrons` instead, which returns the jobs as a record keyed\n * by id. Will be removed in a future release.\n */\nexport async function loadCronJobsFromDirectory(\n directory: string,\n importModule: ModuleImporter = nativeDynamicImport\n): Promise<LoadedCronJob[]> {\n warnDeprecated(\n \"server.loadCronJobsFromDirectory\",\n \"`loadCronJobsFromDirectory` is deprecated; use `loadCrons(dir)`, which returns `{ [id]: definition }`.\"\n );\n return (await legacyLoad(directory, importModule)).jobs;\n}\n\n/**\n * @deprecated Use `loadCrons` instead, with `onSkip` to collect the files it\n * skipped — and `declareCrons` where the jobs belong in the resource graph,\n * which this used to do as a side effect of loading. Will be removed in a\n * future release.\n */\nexport async function loadCronJobsWithDiagnostics(\n directory: string,\n importModule: ModuleImporter = nativeDynamicImport\n): Promise<LoadedCronJobs> {\n warnDeprecated(\n \"server.loadCronJobsWithDiagnostics\",\n \"`loadCronJobsWithDiagnostics` is deprecated; use `loadCrons(dir, { onSkip })`, which returns \" +\n \"`{ [id]: definition }`, and `declareCrons(crons)` to record them in the resource graph.\"\n );\n return legacyLoad(directory, importModule);\n}\n\n/**\n * What the deprecated loaders did: load, declare every job in the resource\n * graph, and hand back normalised jobs. A job the graph refuses is skipped as a\n * problem, as it was when the declaration ran inside the loader.\n */\nasync function legacyLoad(directory: string, importModule: ModuleImporter): Promise<LoadedCronJobs> {\n const { crons, problems } = await readCronsDirectory(directory, importModule);\n const declared: CronsRecord = {};\n for (const [id, definition] of Object.entries(crons)) {\n try {\n declareCron(id, cronResourceOptions(definition));\n declared[id] = definition;\n } catch (err) {\n problems.push(describeLoadFailure(id, err));\n }\n }\n return { jobs: cronJobsFrom(declared), problems };\n}\n\n/**\n * Read a directory of cron files: the definitions that loaded, keyed by id, and\n * one `<file> (<reason>)` per file that will NOT be scheduled.\n *\n * A job that does not load does not run, and the only trace used to be one\n * `warn` per file in the boot log — next to nothing at 3am when the report that\n * should have been mailed was not. So the skips are counted, summarised in one\n * place, and answered by `GET /api/admin/cron`.\n *\n * Never throws, for the same reason the function loader does not: one\n * malformed file must not take the server down, and the other jobs in the\n * directory are still worth scheduling.\n */\nexport async function readCronsDirectory(\n directory: string,\n importModule: ModuleImporter = nativeDynamicImport\n): Promise<{ crons: CronsRecord; problems: string[] }> {\n const crons: CronsRecord = {};\n // Aggregated so a broken job surfaces as one loud summary rather than a\n // warning buried per-file among the boot noise.\n const problems: string[] = [];\n\n if (!fs.existsSync(directory)) {\n return { crons, problems };\n }\n\n const files = fs.readdirSync(directory);\n for (const file of files) {\n if (\n (file.endsWith(\".ts\") || file.endsWith(\".js\")) &&\n // Dotfiles: notably macOS bsdtar AppleDouble sidecars (`._foo.ts`),\n // binary blobs that cannot be imported.\n !file.startsWith(\".\") &&\n !file.includes(\".test.\") &&\n !file.endsWith(\".d.ts\") &&\n file !== \"index.ts\" &&\n file !== \"index.js\"\n ) {\n const filePath = path.join(directory, file);\n try {\n const fileUrl = pathToFileURL(filePath).href;\n\n const mod = await importModule(fileUrl);\n\n const exported: unknown = mod.default;\n\n if (!exported || typeof exported !== \"object\") {\n problems.push(`${file} (no default export)`);\n logger.warn(`[cron] ${file}: no valid default export. Skipping.`);\n continue;\n }\n\n const def = exported as Record<string, unknown>;\n if (typeof def.schedule !== \"string\" || def.schedule.trim() === \"\" || typeof def.handler !== \"function\") {\n problems.push(`${file} (default export has no 'schedule' or no 'handler')`);\n logger.warn(`[cron] ${file}: default export missing required 'schedule' or 'handler'. Skipping.`);\n continue;\n }\n\n const id = path.basename(file, path.extname(file));\n const definition = exported as CronJobDefinition;\n crons[id] = definition;\n logger.info(\n `⏰ Loaded cron job: ${id} (${definition.schedule}` +\n `${definition.timezone ? ` ${definition.timezone}` : \" in the process's local time\"})`\n );\n } catch (err: unknown) {\n const message =\n err instanceof Error ? err.message : String(err);\n problems.push(describeLoadFailure(file, err));\n // At `debug`: the aggregate warning below lists every problem\n // by file, so this line was the same text a second time — and\n // when the throw is a Zod error, that text is ten lines of\n // serialised issues. The reader met it twice before reaching\n // the sentence that says what to do.\n logger.debug(`[cron] Failed to load ${file}: ${message}`);\n }\n }\n }\n\n if (problems.length > 0) {\n // Advice keyed to what went wrong, as the functions loader does:\n // `defineCron` is the remedy for a wrong export shape, not for a typo.\n const syntax = problems.some(p => p.includes(\"(syntax error\"));\n const other = problems.some(p => !p.includes(\"(syntax error\"));\n logger.warn(\n `[cron] ${problems.length} cron file(s) were skipped and will NOT be scheduled:\\n` +\n problems.map((p) => ` - ${p}`).join(\"\\n\") + \"\\n\" +\n [\n ...(syntax ? [SYNTAX_ERROR_ADVICE] : []),\n ...(other ? [\" Fix these or author them with `defineCron(...)` for a typed, compile-checked contract.\"] : [])\n ].join(\"\\n\")\n );\n }\n\n return { crons, problems };\n}\n\n/**\n * The declaration a definition makes: every field a host can read without the\n * handler. Spelled once here so the graph and the scheduler cannot disagree\n * about what a cron is.\n */\nexport function cronResourceOptions(definition: CronJobDefinition): CronResourceOptions {\n return {\n schedule: definition.schedule,\n ...(definition.timezone !== undefined ? { timezone: definition.timezone } : {}),\n ...(definition.description !== undefined ? { description: definition.description } : {}),\n ...(definition.enabled !== undefined ? { enabled: definition.enabled } : {}),\n ...(definition.timeoutSeconds !== undefined ? { timeoutSeconds: definition.timeoutSeconds } : {}),\n ...(definition.catchUpWindowSeconds !== undefined ? { catchUpWindowSeconds: definition.catchUpWindowSeconds } : {}),\n ...(definition.name ? { label: definition.name } : {})\n };\n}\n"],"mappings":"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"}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"cron-scheduler-B04ACoUE.js","names":[],"sources":["../../types/src/types/env_boolean.ts","../src/cron/scale-to-zero.ts","../src/cron/cron-scheduler.ts"],"sourcesContent":["const YES = new Set([\"true\", \"1\", \"yes\", \"on\"]);\nconst NO = new Set([\"false\", \"0\", \"no\", \"off\"]);\n\n/**\n * Read a boolean environment variable — one spelling rule for every reader.\n *\n * `true`, `1`, `yes` and `on` are true; `false`, `0`, `no` and `off` are\n * false. Case and surrounding whitespace are ignored. Anything else — unset,\n * blank, or a value that spells neither — is `undefined`, so the caller's\n * default decides and a typo lands on the side the caller chose:\n *\n * ```ts\n * parseEnvBoolean(env.FORCE_LOCAL_STORAGE) === true // off unless said\n * parseEnvBoolean(env.REBASE_MCP_OPEN_REGISTRATION) !== false // on unless said\n * ```\n *\n * It exists because every reader used to spell this itself, and they\n * disagreed. The reader that mattered tested the raw string for truthiness —\n * `!process.env.FORCE_LOCAL_STORAGE` — and every non-empty string is truthy,\n * so `FORCE_LOCAL_STORAGE=false`, written to say \"there is no durable volume\n * here\", switched the production storage guard off and sent uploads to a\n * container filesystem the next redeploy erased. Beside it, `=== \"true\"` made\n * `DISABLE_DB_ROLE_SWITCHING=1` do nothing and `!== \"false\"` made\n * `REBASE_MCP_OPEN_REGISTRATION=0` leave registration open.\n *\n * The boot schemas in `@rebasepro/server` (`loadEnv`, `loadBootEnv`) accept a\n * strict subset — `true`, `false` and blank — and refuse any other value\n * before the server starts. On that subset they read exactly what this reads,\n * so a variable a schema declares and something else reads lazily cannot mean\n * two different things.\n *\n * It lives in this package, with no dependencies, for the reason\n * {@link storageEnvSuffix} does: the runtime, its drivers and the CLI all read\n * these variables, and a second parser is a second chance to disagree.\n *\n * @group Models\n */\nexport function parseEnvBoolean(value: string | undefined): boolean | undefined {\n if (value === undefined) return undefined;\n const spelled = value.trim().toLowerCase();\n if (YES.has(spelled)) return true;\n if (NO.has(spelled)) return false;\n return undefined;\n}\n","/**\n * Scale-to-zero detection for the cron scheduler.\n *\n * The scheduler drives jobs with in-process `setTimeout`. That works on any\n * always-running instance, but on a platform that freezes or evicts the\n * container between requests (Cloud Run with `--min-instances=0`, AWS Lambda,\n * Vercel functions) the timers simply never fire — the process boots, logs the\n * jobs as registered, and silently runs nothing.\n *\n * None of these platforms expose their scaling floor to the container, so this\n * detection is a heuristic: it identifies the *platform*, not the setting. It\n * is a warning only — it must never influence boot.\n *\n * Environment variables used here were verified against vendor documentation:\n * - `K_SERVICE` / `K_REVISION` / `K_CONFIGURATION` — Cloud Run services\n * (Cloud Run container contract; no variable exposes min-instances).\n * - `CLOUD_RUN_JOB` — Cloud Run jobs (same contract).\n * - `AWS_LAMBDA_FUNCTION_NAME` — reserved AWS Lambda runtime variable.\n * - `VERCEL=1` — Vercel system environment variable, available at runtime.\n * - `KUBERNETES_SERVICE_HOST` — injected into every pod by the kubelet. Used\n * as an *exclusion*: a Deployment pod runs continuously, and Knative on\n * Kubernetes also sets `K_SERVICE`, so a pod is never warned about.\n */\n\nimport { parseEnvBoolean } from \"@rebasepro/types\";\n\n/** Environment variable that permanently silences the scale-to-zero warning. */\nexport const CRON_ALWAYS_ON_ENV = \"REBASE_CRON_ALWAYS_ON\";\n\n/** The subset of `process.env` this module reads. */\nexport type EnvLike = Record<string, string | undefined>;\n\nexport interface FreezableRuntime {\n /** Human-readable platform name, used verbatim in the warning. */\n platform: string;\n /** Names of the environment variables that identified the platform. */\n signals: string[];\n}\n\n/** Minimal shape of a registered job needed to build the warning. */\nexport interface WarnableJob {\n id: string;\n enabled: boolean;\n}\n\nexport interface ScaleToZeroWarning {\n message: string;\n data: Record<string, unknown>;\n}\n\n/**\n * Identify a runtime whose instances can be frozen or torn down between\n * requests. Returns `undefined` when the platform is unknown or known to run\n * continuously.\n */\nexport function detectFreezableRuntime(env: EnvLike = process.env): FreezableRuntime | undefined {\n // A Kubernetes pod (GKE, EKS, self-hosted) runs continuously. Knative and\n // Cloud Run for Anthos set K_SERVICE *inside* a pod, so this exclusion has\n // to come first or every Knative pod would be a false positive.\n if (env.KUBERNETES_SERVICE_HOST) return undefined;\n\n if (env.K_SERVICE) {\n const signals = [\"K_SERVICE\"];\n if (env.K_REVISION) signals.push(\"K_REVISION\");\n if (env.K_CONFIGURATION) signals.push(\"K_CONFIGURATION\");\n return { platform: \"Cloud Run\", signals };\n }\n\n if (env.CLOUD_RUN_JOB) {\n return { platform: \"Cloud Run Jobs\", signals: [\"CLOUD_RUN_JOB\"] };\n }\n\n if (env.AWS_LAMBDA_FUNCTION_NAME) {\n return { platform: \"AWS Lambda\", signals: [\"AWS_LAMBDA_FUNCTION_NAME\"] };\n }\n\n if (parseEnvBoolean(env.VERCEL) === true) {\n return { platform: \"Vercel\", signals: [\"VERCEL\"] };\n }\n\n return undefined;\n}\n\n/** How many job ids to name before collapsing the rest into \"+N more\". */\nconst MAX_NAMED_JOBS = 10;\n\n/**\n * Build the boot-time warning, or `undefined` when it does not apply.\n *\n * Fires only when all of the following hold:\n * 1. `NODE_ENV=production` — a laptop or CI run is not at risk.\n * 2. At least one *enabled* job is registered — nothing to lose otherwise.\n * 3. The environment looks like a freezable platform (see above).\n * 4. `REBASE_CRON_ALWAYS_ON` is not set to a truthy value.\n */\nexport function buildScaleToZeroWarning(\n jobs: WarnableJob[],\n env: EnvLike = process.env\n): ScaleToZeroWarning | undefined {\n if (env.NODE_ENV !== \"production\") return undefined;\n if (parseEnvBoolean(env[CRON_ALWAYS_ON_ENV]) === true) return undefined;\n\n const enabled = jobs.filter((job) => job.enabled).map((job) => job.id);\n if (enabled.length === 0) return undefined;\n\n const runtime = detectFreezableRuntime(env);\n if (!runtime) return undefined;\n\n const named = enabled.slice(0, MAX_NAMED_JOBS);\n const list = enabled.length > named.length\n ? `${named.join(\", \")} (+${enabled.length - named.length} more)`\n : named.join(\", \");\n\n const message = `[cron] ${runtime.platform} detected — in-process timers do not fire while an instance is frozen or scaled to zero, so ${enabled.length} enabled job(s) may never run: ${list}; drive them from an external scheduler instead (POST /api/cron/:id/trigger, e.g. Cloud Scheduler). ${runtime.platform} does not expose its scaling floor to the container, so an always-warm deployment cannot be confirmed from inside the process — set ${CRON_ALWAYS_ON_ENV}=1 to silence this if at least one instance is pinned warm.`;\n\n return {\n message,\n data: {\n platform: runtime.platform,\n signals: runtime.signals,\n jobs: enabled\n }\n };\n}\n","import type {\n CronJobDefinition,\n CronJobStatus,\n CronJobLogEntry,\n CronJobRunState,\n CronJobContext,\n RejectedCronJob\n} from \"@rebasepro/types\";\nimport type { RebaseServerClient } from \"@rebasepro/types\";\nimport { hostname } from \"node:os\";\nimport { randomUUID } from \"node:crypto\";\nimport type { LoadedCronJob } from \"./cron-loader\";\nimport type { CronJobRunSummary, CronStore } from \"./cron-store\";\nimport { logger, redactSensitiveText, stringifyForLog } from \"../utils/logger.js\";\nimport { buildScaleToZeroWarning } from \"./scale-to-zero.js\";\n\n// ─── Cron expression parser (minimal, no external dependency) ────────\n// Supports standard 5-field cron (minute hour dom month dow).\n// Returns the next Date after `after` that matches the expression.\n\n/**\n * Expand a single cron field into an ordered array of allowed values.\n * Supports: `*`, `N`, `N-M`, `N/S`, `N-M/S`, `*\\/S`, and comma-separated combinations.\n */\nfunction expandCronField(field: string, min: number, max: number): number[] {\n const results = new Set<number>();\n for (const segment of field.split(\",\")) {\n const trimmed = segment.trim();\n if (trimmed === \"*\") {\n for (let i = min; i <= max; i++) results.add(i);\n } else if (trimmed.includes(\"/\")) {\n const [rangeStr, stepStr] = trimmed.split(\"/\");\n const step = parseInt(stepStr, 10);\n if (isNaN(step) || step <= 0) {\n throw new Error(`Invalid step value \"${stepStr}\" in cron field \"${field}\"`);\n }\n let start = min;\n let end = max;\n if (rangeStr !== \"*\") {\n if (rangeStr.includes(\"-\")) {\n const [a, b] = rangeStr.split(\"-\").map(Number);\n start = a;\n end = b;\n } else {\n start = parseInt(rangeStr, 10);\n }\n }\n for (let i = start; i <= end; i += step) results.add(i);\n } else if (trimmed.includes(\"-\")) {\n const [a, b] = trimmed.split(\"-\").map(Number);\n for (let i = a; i <= b; i++) results.add(i);\n } else {\n const val = parseInt(trimmed, 10);\n if (isNaN(val)) {\n throw new Error(`Invalid value \"${trimmed}\" in cron field \"${field}\"`);\n }\n results.add(val);\n }\n }\n return [...results].sort((a, b) => a - b);\n}\n\n/**\n * Validates a standard 5-field cron expression structurally and semantically.\n * Returns `{ valid: true }` or `{ valid: false, reason: string }`.\n */\nexport function validateCronExpression(schedule: string): { valid: true } | { valid: false; reason: string } {\n if (!schedule || typeof schedule !== \"string\") {\n return { valid: false,\nreason: \"Schedule must be a non-empty string\" };\n }\n const parts = schedule.trim().split(/\\s+/);\n if (parts.length !== 5) {\n return { valid: false,\nreason: `Expected 5 fields, got ${parts.length}` };\n }\n const fieldRanges: [string, number, number][] = [\n [\"minute\", 0, 59],\n [\"hour\", 0, 23],\n [\"day of month\", 1, 31],\n [\"month\", 1, 12],\n [\"day of week\", 0, 6]\n ];\n for (let i = 0; i < 5; i++) {\n const [name, min, max] = fieldRanges[i];\n try {\n const values = expandCronField(parts[i], min, max);\n if (values.length === 0) {\n return { valid: false,\nreason: `${name} field \"${parts[i]}\" produces no values` };\n }\n for (const v of values) {\n if (v < min || v > max) {\n return { valid: false,\nreason: `${name} field value ${v} out of range [${min}–${max}]` };\n }\n }\n } catch (err) {\n return { valid: false,\nreason: `${name} field: ${err instanceof Error ? err.message : String(err)}` };\n }\n }\n return { valid: true };\n}\n\n/** The five cron fields, pre-expanded into the values each one allows. */\ninterface CronFields {\n minutes: number[];\n hours: number[];\n doms: number[];\n months: number[];\n dows: number[];\n}\n\n/** Expand all five fields of an expression. Throws on invalid expressions. */\nfunction parseCronFields(expression: string): CronFields {\n const parts = expression.trim().split(/\\s+/);\n if (parts.length < 5) {\n throw new Error(`Invalid cron expression: \"${expression}\". Expected 5 fields.`);\n }\n const [minField, hourField, domField, monField, dowField] = parts;\n return {\n minutes: expandCronField(minField, 0, 59),\n hours: expandCronField(hourField, 0, 23),\n doms: expandCronField(domField, 1, 31),\n months: expandCronField(monField, 1, 12),\n dows: expandCronField(dowField, 0, 6) // 0=Sunday\n };\n}\n\n/**\n * Whether an IANA zone name is one this runtime can read a schedule in.\n *\n * `Intl` is the authority: it throws a RangeError on a name it does not know,\n * which is the only check that tracks the tz database the process actually\n * ships. A misspelled zone must fail when the job loads, not silently read\n * the schedule as local time.\n */\nexport function isValidTimeZone(zone: string): boolean {\n try {\n new Intl.DateTimeFormat(\"en-US\", { timeZone: zone });\n return true;\n } catch {\n return false;\n }\n}\n\n/** Wall-clock parts of an instant, in a zone, as the cron fields see them. */\ninterface WallClock {\n year: number;\n minute: number;\n hour: number;\n dom: number;\n month: number;\n dow: number;\n}\n\nconst formatters = new Map<string, Intl.DateTimeFormat>();\nconst DOW: Record<string, number> = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };\n\nfunction wallClockIn(candidate: Date, zone: string): WallClock {\n let formatter = formatters.get(zone);\n if (!formatter) {\n formatter = new Intl.DateTimeFormat(\"en-US\", {\n timeZone: zone,\n hourCycle: \"h23\",\n weekday: \"short\",\n year: \"numeric\",\n month: \"numeric\",\n day: \"numeric\",\n hour: \"numeric\",\n minute: \"numeric\"\n });\n formatters.set(zone, formatter);\n }\n const parts: Record<string, string> = {};\n for (const part of formatter.formatToParts(candidate)) parts[part.type] = part.value;\n return {\n year: Number(parts.year),\n minute: Number(parts.minute),\n hour: Number(parts.hour),\n dom: Number(parts.day),\n month: Number(parts.month),\n dow: DOW[parts.weekday] ?? candidate.getDay()\n };\n}\n\n/**\n * The wall clock an instant reads in `zone` when one is named, else in the\n * process's own zone — which is whatever the host is set to, UTC in nearly\n * every container. A schedule that names its zone means the same wall-clock\n * hour on every host it runs on.\n */\nfunction wallClockOf(instantMs: number, zone?: string): WallClock {\n const candidate = new Date(instantMs);\n if (zone) return wallClockIn(candidate, zone);\n return {\n year: candidate.getFullYear(),\n minute: candidate.getMinutes(),\n hour: candidate.getHours(),\n dom: candidate.getDate(),\n month: candidate.getMonth() + 1, // getMonth is 0-11\n dow: candidate.getDay()\n };\n}\n\n/**\n * The zone's offset from UTC at an instant: its wall clock read back as UTC,\n * minus the instant. Two instants with the same offset have wall clocks\n * exactly as far apart as the instants themselves.\n */\nfunction offsetAt(instantMs: number, wall: WallClock): number {\n return Date.UTC(wall.year, wall.month - 1, wall.dom, wall.hour, wall.minute) - instantMs;\n}\n\n/** Whether a wall-clock day — month, day of month, weekday — can hold a slot. */\nfunction dayMatches(wall: WallClock, fields: CronFields): boolean {\n return fields.months.includes(wall.month)\n && fields.doms.includes(wall.dom)\n && fields.dows.includes(wall.dow);\n}\n\n/** Whether a wall-clock minute matches every field of the expression. */\nfunction wallMatches(wall: WallClock, fields: CronFields): boolean {\n return dayMatches(wall, fields)\n && fields.hours.includes(wall.hour)\n && fields.minutes.includes(wall.minute);\n}\n\nconst MINUTES_PER_DAY = 1440;\n\n/**\n * How many wall-clock minutes from a non-matching `wall` to the first later\n * wall minute that could match. Never past the next wall midnight, so the\n * minutes in between share `wall`'s day and every one of them is a miss.\n */\nfunction wallMinutesToNextCandidate(wall: WallClock, fields: CronFields): number {\n const minuteOfDay = wall.hour * 60 + wall.minute;\n if (!dayMatches(wall, fields)) return MINUTES_PER_DAY - minuteOfDay;\n if (!fields.hours.includes(wall.hour)) {\n const nextHour = fields.hours.find(hour => hour > wall.hour);\n return nextHour === undefined ? MINUTES_PER_DAY - minuteOfDay : nextHour * 60 - minuteOfDay;\n }\n const nextMinute = fields.minutes.find(minute => minute > wall.minute);\n return nextMinute === undefined ? 60 - wall.minute : nextMinute - wall.minute;\n}\n\n/**\n * The mirror of {@link wallMinutesToNextCandidate}: how many wall-clock\n * minutes back from a non-matching `wall` to the latest earlier wall minute\n * that could match. Never before 23:59 of the previous wall day.\n */\nfunction wallMinutesToPreviousCandidate(wall: WallClock, fields: CronFields): number {\n const minuteOfDay = wall.hour * 60 + wall.minute;\n if (!dayMatches(wall, fields)) return minuteOfDay + 1;\n if (!fields.hours.includes(wall.hour)) {\n const previousHour = [...fields.hours].reverse().find(hour => hour < wall.hour);\n return previousHour === undefined ? minuteOfDay + 1 : minuteOfDay - (previousHour * 60 + 59);\n }\n const previousMinute = [...fields.minutes].reverse().find(minute => minute < wall.minute);\n return previousMinute === undefined ? wall.minute + 1 : wall.minute - previousMinute;\n}\n\n/**\n * How far forward to look for the next matching slot.\n *\n * Four years and a day, not one year. `0 0 29 2 *` — run on 29 February — is a\n * legitimate expression whose slot can be almost four years out, and a one-year\n * search never found it.\n */\nconst MAX_SLOT_SEARCH_MINUTES = 4 * 525960 + 1440;\n\nconst MINUTE_MS = 60_000;\n\n/**\n * The first real minute in `[startMs, endMs)`, stepping in `direction`, whose\n * wall clock matches `fields` — the same answer as testing every minute in\n * turn, without testing every minute.\n *\n * The search moves through *real* minutes and only reads the wall clock, never\n * steps it: across a daylight-saving change a wall-clock minute is not a real\n * one. Falling back, a wall-clock step from 02:59 summer time lands on 03:00\n * winter time and skips the repeated hour; inside it, the \"next\" minute can be\n * an hour in the past. That is why this used to test one real minute at a\n * time — and a yearly job named in a zone cost half a million `Intl` calls,\n * blocking the event loop for a third of a second on every re-arm, and two\n * seconds for 29 February.\n *\n * Now it hops. From a miss, {@link wallMinutesToNextCandidate} says how many\n * wall minutes cannot match (the rest of a day that is the wrong date, the\n * rest of an hour that is the wrong hour, the minutes before the next listed\n * one). While the zone's offset holds, that many wall minutes are exactly\n * that many real minutes, so the hop is taken when the offset at both ends is\n * the same. When it differs, a transition lies inside the hop: the search\n * bisects for the first minute on the new offset and resumes there — every\n * minute before it is on the old offset, so its wall clock is inside the\n * stretch already known to miss. A hop is at most a day, and the one thing\n * this assumes is that no zone changes its offset and changes it back within\n * a single day, which none in the tz database does. Each day costs one\n * wall-clock read, plus about a dozen for each transition crossed.\n *\n * `direction: -1` walks back from `startMs` to `endMs` (inclusive) with the\n * mirror of the same hop, for {@link findMostRecentSlot}.\n */\nfunction searchSlot(\n fields: CronFields,\n startMs: number,\n endMs: number,\n direction: 1 | -1,\n zone?: string\n): number | undefined {\n const inWindow = (instantMs: number) => direction === 1 ? instantMs < endMs : instantMs >= endMs;\n let current = startMs;\n let wall = wallClockOf(current, zone);\n while (inWindow(current)) {\n if (wallMatches(wall, fields)) return current;\n const skip = direction === 1\n ? wallMinutesToNextCandidate(wall, fields)\n : wallMinutesToPreviousCandidate(wall, fields);\n const target = current + direction * skip * MINUTE_MS;\n const targetWall = wallClockOf(target, zone);\n const offset = offsetAt(current, wall);\n if (skip === 1 || offsetAt(target, targetWall) === offset) {\n current = target;\n wall = targetWall;\n continue;\n }\n // The offset changes inside the hop. Bisect for the first minute, in\n // the direction of travel, that is no longer on `offset`.\n let held = current;\n let changed = target;\n let changedWall = targetWall;\n while (Math.abs(changed - held) > MINUTE_MS) {\n const middle = held + direction * Math.floor(Math.abs(changed - held) / MINUTE_MS / 2) * MINUTE_MS;\n const middleWall = wallClockOf(middle, zone);\n if (offsetAt(middle, middleWall) === offset) {\n held = middle;\n } else {\n changed = middle;\n changedWall = middleWall;\n }\n }\n current = changed;\n wall = changedWall;\n }\n return undefined;\n}\n\n/**\n * Calculate the next Date after `after` that matches the cron expression.\n * Throws on invalid expressions.\n */\nexport function parseCronExpression(expression: string, after: Date, timezone?: string): Date {\n const fields = parseCronFields(expression);\n\n // From `after + 1 minute`, in real minutes — see `searchSlot`.\n const start = new Date(after);\n start.setUTCSeconds(0, 0);\n const startMs = start.getTime() + MINUTE_MS;\n const slot = searchSlot(fields, startMs, startMs + MAX_SLOT_SEARCH_MINUTES * MINUTE_MS, 1, timezone);\n if (slot !== undefined) return new Date(slot);\n\n // No slot inside the window. Refuse rather than invent one.\n //\n // This used to return `after + 1 minute`, which is indistinguishable from a\n // schedule that really does fire every minute — so an expression with no\n // reachable slot ran sixty times an hour, forever. `0 0 29 2 *` was caught\n // by it while the search window was a single year: a job meant to run once\n // every four years became the busiest job on the deployment.\n //\n // The caller schedules inside a `try` and reports a job it could not\n // schedule, which is the correct outcome for an expression that names no\n // time. Genuinely impossible dates (`0 0 31 2 *`) land here too, and should.\n throw new Error(\n `Cron expression \"${expression}\" has no matching time within ` +\n `${Math.round(MAX_SLOT_SEARCH_MINUTES / 525960)} years of ${after.toISOString()}. ` +\n \"Check the day-of-month and month fields — a date such as 31 February never occurs.\"\n );\n}\n\n/**\n * The latest slot matching `expression` within the inclusive window\n * `[from, to]`, or `undefined` when the expression has no slot in it.\n *\n * Walks backwards from `to`, so the first hit is already the answer — in the\n * common case (a job that ran normally moments ago) that is a handful of\n * steps, not a scan of the whole window.\n *\n * `to`'s own minute is included: an instance booting at 06:00:30 has *not* run\n * the 06:00 slot — `parseCronExpression` already skipped past it to tomorrow —\n * so that slot is genuinely missed and must be a candidate.\n *\n * Seconds and milliseconds are zeroed to match how `parseCronExpression`\n * builds a slot, so the same wall-clock slot serialises to a byte-identical\n * ISO string down either path. The claim key depends on that.\n */\nexport function findMostRecentSlot(expression: string, from: Date, to: Date, timezone?: string): Date | undefined {\n const fields = parseCronFields(expression);\n\n // Real minutes, as in `parseCronExpression`: a local-time step back from\n // 02:00 winter time lands on 01:59 summer time and walks over the repeated\n // hour.\n const start = new Date(to);\n start.setUTCSeconds(0, 0);\n const startMs = start.getTime();\n const floorMs = Math.max(from.getTime(), startMs - (MAX_SLOT_SEARCH_MINUTES - 1) * MINUTE_MS);\n const slot = searchSlot(fields, startMs, floorMs, -1, timezone);\n return slot === undefined ? undefined : new Date(slot);\n}\n\n// ─── In-memory ring buffer for logs ──────────────────────────────────\n\nconst MAX_LOGS_PER_JOB = 50;\n\n/**\n * What one run keeps of its `ctx.log` lines: up to 500 lines or 64 KB,\n * whichever comes first. The lines past that are counted, and one line at the\n * end says how many there were; every line still reaches the server log.\n *\n * Uncapped, a job logging one line per item kept them all — in the 50-run ring\n * per job, in a `cron_logs` row, and in every history read: a per-minute sync\n * of 1,000 items held 4 MB per job in memory and wrote 115 MB a day.\n */\nexport const MAX_CAPTURED_LOG_LINES = 500;\nexport const MAX_CAPTURED_LOG_BYTES = 64 * 1024;\n\n/**\n * A run's `ctx.log` capture, capped at {@link MAX_CAPTURED_LOG_LINES} and\n * {@link MAX_CAPTURED_LOG_BYTES}. The kept lines are the first ones: once one\n * line is dropped, every later one is too, so the history reads as a prefix of\n * the run's output and never as lines with gaps between them.\n */\nfunction createLogCapture(firstLine?: string) {\n const lines: string[] = [];\n let bytes = 0;\n let dropped = 0;\n let closed = false;\n const capture = {\n add(line: string): void {\n if (closed) return;\n const size = Buffer.byteLength(line, \"utf8\");\n if (dropped === 0 && lines.length < MAX_CAPTURED_LOG_LINES && bytes + size <= MAX_CAPTURED_LOG_BYTES) {\n lines.push(line);\n bytes += size;\n return;\n }\n dropped++;\n },\n /** The lines kept, and the line that says what was not. Later `add`s are ignored. */\n close(): string[] {\n if (!closed && dropped > 0) {\n lines.push(`… ${dropped} more line${dropped === 1 ? \"\" : \"s\"} not kept — see the server log`);\n }\n closed = true;\n return lines;\n }\n };\n if (firstLine !== undefined) capture.add(firstLine);\n return capture;\n}\n\n/**\n * Minimum milliseconds between scheduled executions of the same job.\n * Prevents tight re-execution loops caused by jitter or clock drift.\n */\nconst MIN_SCHEDULE_INTERVAL_MS = 5_000; // 5 seconds\n\n/**\n * Largest delay setTimeout can hold. Node stores it in a 32-bit signed int;\n * anything larger silently clamps to 1ms and fires immediately, so a slot\n * further out than this must be reached in hops rather than one timer.\n */\nconst MAX_TIMER_DELAY_MS = 2_147_483_647; // 2^31 - 1, ~24.8 days\n\n/**\n * `setTimeout` for a delay that may exceed {@link MAX_TIMER_DELAY_MS}: armed in\n * hops no longer than the ceiling, re-measured against the deadline on each\n * wake. Returns the function that cancels it.\n */\nfunction setLongTimeout(callback: () => void, delayMs: number): () => void {\n const deadline = Date.now() + delayMs;\n let handle: ReturnType<typeof setTimeout>;\n const arm = () => {\n handle = setTimeout(() => {\n if (Date.now() < deadline) arm();\n else callback();\n }, Math.min(Math.max(deadline - Date.now(), 0), MAX_TIMER_DELAY_MS));\n };\n arm();\n return () => clearTimeout(handle);\n}\n\n/** A run's timeout when its definition names none. */\nconst DEFAULT_TIMEOUT_SECONDS = 300;\n\n/**\n * How often a started scheduler deletes slot claims and run history past\n * retention. Both accrue one row per job per fire, so a scheduler that lives\n * for months needs to prune while it runs, not only when it next boots.\n */\nconst CLAIM_SWEEP_INTERVAL_MS = 60 * 60_000;\n\n/**\n * How long a run lease outlasts the run's own timeout.\n *\n * The lease is timed on the database's clock from the moment it is taken, the\n * timeout on this process's from a moment later; without a margin a lease\n * could lapse a beat before its run is aborted and released, and another\n * process start the job alongside it.\n */\nconst LEASE_GRACE_SECONDS = 30;\n\n/**\n * The lease a run with no timeout (`timeoutSeconds: Infinity`) holds.\n *\n * A lease is released when its run ends, so this only matters in two cases.\n * The holder crashed: the job is blocked — every trigger answered \"already\n * executing\", every slot skipped — until the lease lapses, so it must lapse\n * within an hour rather than never. The run is still going after an hour:\n * from then on another process may start the job beside it. A job that\n * legitimately runs for hours should say so with a finite `timeoutSeconds`,\n * which its lease then follows.\n */\nconst MAX_UNBOUNDED_LEASE_SECONDS = 3600;\n\n/**\n * What {@link CronScheduler.startJob} answers: the run began at `startedAt`\n * (its history entry will carry the same timestamp), or it did not start and\n * `log` is the skip that says why.\n */\nexport type StartedCronRun =\n | { started: true; startedAt: string }\n | { started: false; log: CronJobLogEntry };\n\n/**\n * Whether a log entry records a run that did not happen because one was\n * already executing — on this process, or on another that holds the job's run\n * lease. The shape is the documented marker of a skip, the one the Studio\n * panel reads.\n */\nexport function isAlreadyExecutingSkip(entry: CronJobLogEntry): boolean {\n const result = entry.result;\n return typeof result === \"object\" && result !== null\n && \"skipped\" in result && result.skipped === true\n && \"reason\" in result && result.reason === \"already_executing\";\n}\n\n/**\n * Why `timeoutSeconds` cannot be used, or `undefined` when it can. Infinity is\n * a timeout that never fires; zero, a negative number or NaN would fail every\n * run the moment it started.\n */\nfunction invalidTimeoutReason(timeoutSeconds: number | undefined): string | undefined {\n if (timeoutSeconds === undefined || timeoutSeconds === Infinity) return undefined;\n if (typeof timeoutSeconds === \"number\" && Number.isFinite(timeoutSeconds) && timeoutSeconds > 0) return undefined;\n return `timeoutSeconds must be a positive number of seconds, or Infinity for none — got ${String(timeoutSeconds)}`;\n}\n\n// ─── CronScheduler ───────────────────────────────────────────────────\n\ninterface RegisteredJob {\n id: string;\n definition: CronJobDefinition;\n enabled: boolean;\n state: CronJobRunState;\n lastRunAt?: Date;\n nextRunAt?: Date;\n lastDurationMs?: number;\n lastError?: string;\n totalRuns: number;\n totalFailures: number;\n timerId?: ReturnType<typeof setTimeout>;\n logs: CronJobLogEntry[];\n /** True while a handler is actively executing (prevents concurrent runs). */\n executing: boolean;\n /**\n * The next slot a listing showed, on a process whose scheduler is not\n * started — see {@link CronScheduler.listedNextRun}.\n */\n listedSlot?: ListedSlot;\n}\n\n/**\n * A next slot computed for a listing, with what it was computed from: the\n * schedule, the zone, and the instant it was computed at.\n */\ninterface ListedSlot {\n schedule: string;\n timezone?: string;\n computedAt: number;\n slot: Date;\n}\n\n/**\n * What this process learned from the store about a job, for a listing: another\n * process running it, and — on a process whose scheduler is not started — its\n * run history and the slot the scheduler will fire next.\n */\ninterface FleetView {\n runningElsewhere?: boolean;\n summary?: CronJobRunSummary;\n nextRunAt?: Date;\n}\n\n/**\n * Whether a run may go ahead. `token` is the lease to release when it ends —\n * absent when no lease was taken, because the store has none or could not\n * answer.\n */\ntype LeaseOutcome =\n | { acquired: true; token?: string }\n | { acquired: false; holder?: string };\n\n/** A job the scheduler refused, with the definition it was refused from. */\ninterface RefusedJob {\n job: RejectedCronJob;\n definition: CronJobDefinition;\n}\n\nexport class CronScheduler {\n private jobs = new Map<string, RegisteredJob>();\n private rejected = new Map<string, RefusedJob>();\n private started = false;\n private store?: CronStore;\n private client?: RebaseServerClient;\n /**\n * Work `stop()` has to wait for: every run executing right now, and every\n * run's log write still on its way to the store.\n */\n private inFlight = new Set<Promise<unknown>>();\n /** The controller that ends each executing run — what `stop()` aborts. */\n private runControllers = new Set<AbortController>();\n /**\n * This process, as a run lease names it: what \"already executing on …\"\n * tells an operator. Each run adds its own suffix, so a release can only\n * ever clear the lease that run took.\n */\n private readonly instanceLabel = `${hostname()}:${process.pid}`;\n /** The hourly claim- and log-retention sweep, while the scheduler is started with a store. */\n private claimSweepTimer?: ReturnType<typeof setInterval>;\n private sweepingClaims = false;\n private sweepingLogs = false;\n\n /**\n * Set the server singleton to make it available to cron job handlers.\n *\n * `RebaseServerClient`, not `RebaseClient`: the object `init.ts` passes is\n * the same one it registers as the singleton, so this was always the true\n * type — and the wider annotation is what let `ctx.client.data` look like a\n * user-scoped plane inside a cron, when it is the admin-scoped one.\n */\n setClient(client: RebaseServerClient): void {\n this.client = client;\n }\n\n /**\n * Attach a persistence store for cron logs.\n * When set, execution logs are written to the database after each run,\n * and counters are seeded from the database on start.\n */\n setStore(store: CronStore): void {\n this.store = store;\n }\n\n /**\n * Register a batch of loaded cron jobs.\n *\n * If the scheduler is already started, newly registered jobs are\n * automatically scheduled (so late-registered jobs don't sit idle).\n *\n * Validates the cron schedule on registration — invalid schedules\n * are rejected with a warning and the job is NOT registered.\n */\n registerJobs(loadedJobs: LoadedCronJob[]): void {\n for (const loaded of loadedJobs) {\n // Validate schedule up-front — reject invalid schedules\n const validation = validateCronExpression(loaded.definition.schedule);\n if (!validation.valid) {\n logger.error(`[cron] Rejecting job \"${loaded.id}\": invalid schedule \"${loaded.definition.schedule}\" — ${validation.reason}`);\n // Kept, not just logged. A rejected job is absent from\n // `listJobs()`, so from the Studio panel it is indistinguishable\n // from a file that was never written — and the commonest reason\n // to land here is a 6-field expression copied from a tool that\n // supports seconds, which is a one-character fix nobody could\n // see without boot-log access.\n this.refuse(loaded, validation.reason);\n continue;\n }\n // Rejected, not read as local time: a misspelled zone that fell\n // back silently would fire at the wrong hour on every host and\n // look like a scheduler bug. Kept in `rejected` for the same reason\n // a bad schedule is — otherwise the panel cannot tell it from a\n // file nobody wrote.\n if (loaded.definition.timezone !== undefined && !isValidTimeZone(loaded.definition.timezone)) {\n const reason =\n `unknown timezone \"${loaded.definition.timezone}\" — ` +\n 'use an IANA name such as \"Europe/Madrid\" or \"UTC\"';\n logger.error(`[cron] Rejecting job \"${loaded.id}\": ${reason}.`);\n this.refuse(loaded, reason);\n continue;\n }\n // Same treatment: a timeout that fails every run the moment it\n // starts is a configuration error, not a run-time one.\n const timeoutProblem = invalidTimeoutReason(loaded.definition.timeoutSeconds);\n if (timeoutProblem) {\n logger.error(`[cron] Rejecting job \"${loaded.id}\": ${timeoutProblem}.`);\n this.refuse(loaded, timeoutProblem);\n continue;\n }\n // A re-register that now validates clears the earlier complaint.\n this.rejected.delete(loaded.id);\n\n const existing = this.jobs.get(loaded.id);\n if (existing) {\n logger.warn(`[cron] Duplicate cron job id: \"${loaded.id}\". Overwriting.`);\n this.stopJob(loaded.id);\n }\n\n const enabled = loaded.definition.enabled !== false;\n\n const job: RegisteredJob = {\n id: loaded.id,\n definition: loaded.definition,\n enabled,\n state: enabled ? \"idle\" : \"disabled\",\n totalRuns: 0,\n totalFailures: 0,\n logs: [],\n executing: false\n };\n this.jobs.set(loaded.id, job);\n\n // If the scheduler is already running, auto-schedule new jobs\n if (this.started && this.shouldArm(job)) {\n this.scheduleNext(loaded.id);\n }\n }\n }\n\n /**\n * Start the scheduler — begins ticking all enabled jobs.\n */\n start(): void {\n if (this.started) return;\n this.started = true;\n\n // Seed counters from DB (non-blocking — scheduler starts immediately)\n if (this.store) {\n this.store.fetchJobStats().then((stats) => {\n for (const [jobId, data] of stats) {\n const job = this.jobs.get(jobId);\n if (job) {\n job.totalRuns = data.totalRuns;\n job.totalFailures = data.totalFailures;\n if (data.lastRunAt) {\n job.lastRunAt = new Date(data.lastRunAt);\n }\n }\n }\n }).catch((err) => {\n logger.warn(\"[cron] Failed to seed job stats from database\", { error: err });\n });\n }\n\n for (const [id, job] of this.jobs) {\n if (this.shouldArm(job)) {\n this.scheduleNext(id);\n }\n }\n if (!this.store) {\n logger.warn(\"[cron] No cron store attached — runs are uncoordinated; with multiple app instances every instance will execute every job\");\n }\n this.warnIfScaleToZero();\n\n // Recover slots that elapsed while nothing was ticking. Deliberately\n // not awaited: catch-up reaches the database and runs handlers, and\n // boot must not wait on either. Its own errors are contained inside.\n void this.catchUpMissedSlots();\n\n // Off the boot path too, and then hourly. It cannot take a claim the\n // catch-up is asking about: a job's latest claim is never swept. The\n // first log sweep is also what counts a history that predates the run\n // counters — a backlog it works through in batches, not in the boot.\n if (this.store?.sweepClaims || this.store?.sweepLogs) {\n const sweep = () => {\n void this.sweepClaims();\n void this.sweepLogs();\n };\n sweep();\n this.claimSweepTimer = setInterval(sweep, CLAIM_SWEEP_INTERVAL_MS);\n this.claimSweepTimer.unref?.();\n }\n\n logger.info(`⏰ Cron scheduler started with ${this.jobs.size} job(s)`);\n }\n\n /** Delete slot claims past retention. Failures are logged; the next hour tries again. */\n private async sweepClaims(): Promise<void> {\n const store = this.store;\n if (!store?.sweepClaims || this.sweepingClaims) return;\n this.sweepingClaims = true;\n try {\n await store.sweepClaims();\n } catch (err) {\n logger.warn(\"[cron] The claim retention sweep failed; it runs again within the hour\", { error: err });\n } finally {\n this.sweepingClaims = false;\n }\n }\n\n /**\n * Delete run history past retention, and count the runs not counted yet.\n * Failures are logged; the next hour tries again, from where this one\n * stopped — each batch it finished is committed.\n */\n private async sweepLogs(): Promise<void> {\n const store = this.store;\n if (!store?.sweepLogs || this.sweepingLogs) return;\n this.sweepingLogs = true;\n try {\n const { counted } = await store.sweepLogs();\n if (counted > 0) {\n logger.info(`[cron] Counted ${counted} earlier run(s) into the jobs' run totals`);\n }\n } catch (err) {\n logger.warn(\"[cron] The run history sweep failed; it runs again within the hour\", { error: err });\n } finally {\n this.sweepingLogs = false;\n }\n }\n\n /**\n * Stop the scheduler: clear every timer, then wait for the runs executing\n * right now — for at most `timeoutMs` when given.\n *\n * A run still going when the budget runs out has its `ctx.signal` aborted\n * and ends there, recorded as a failure that says why. Its slot stays\n * claimed, so no other instance re-runs it; a handler that must not be cut\n * short should watch its signal and leave its work resumable.\n *\n * Nothing is scheduled after `stop()`, whether or not the returned promise\n * is awaited: the timers are cleared before it first yields.\n */\n async stop(timeoutMs?: number): Promise<void> {\n this.started = false;\n for (const [id] of this.jobs) {\n this.stopJob(id);\n }\n if (this.claimSweepTimer) {\n clearInterval(this.claimSweepTimer);\n this.claimSweepTimer = undefined;\n }\n if (this.inFlight.size === 0) return;\n\n const settled = Promise.allSettled([...this.inFlight]).then(() => true);\n if (timeoutMs === undefined) {\n await settled;\n return;\n }\n let budget: ReturnType<typeof setTimeout> | undefined;\n const finished = await Promise.race([\n settled,\n new Promise<false>((resolve) => {\n budget = setTimeout(() => resolve(false), timeoutMs);\n if (budget && typeof budget === \"object\" && \"unref\" in budget) {\n budget.unref();\n }\n })\n ]);\n clearTimeout(budget);\n if (finished || this.runControllers.size === 0) return;\n\n logger.warn(`[cron] ${this.runControllers.size} run(s) still executing after ${timeoutMs}ms — aborting them`);\n for (const controller of this.runControllers) {\n controller.abort(new Error(\"The server is shutting down; the run was stopped before it finished\"));\n }\n }\n\n /**\n * List all registered jobs with their current status.\n */\n listJobs(): CronJobStatus[] {\n return [...this.jobs.values()].map((job) => this.toStatus(job));\n }\n\n /** Keep a refused job, so the admin surface can say why it never runs. */\n private refuse(loaded: LoadedCronJob, reason: string): void {\n this.rejected.set(loaded.id, {\n job: {\n id: loaded.id,\n name: loaded.definition.name ?? loaded.id,\n schedule: loaded.definition.schedule,\n reason\n },\n definition: loaded.definition\n });\n }\n\n /**\n * Jobs that loaded but whose schedule the scheduler refused.\n *\n * Kept apart from {@link listJobs} because they are not jobs — nothing will\n * run them — but they must be reachable, or \"my cron is missing\" and \"my\n * cron will never fire\" look identical from the admin panel.\n */\n listRejectedJobs(): RejectedCronJob[] {\n return [...this.rejected.values()].map(refused => refused.job);\n }\n\n /**\n * {@link listRejectedJobs}, those whose definition matches — how a surface\n * finds a refused job by what it is, as {@link jobIdsWhere} does for the\n * registered ones.\n */\n rejectedJobsWhere(predicate: (definition: CronJobDefinition) => boolean): RejectedCronJob[] {\n return [...this.rejected.values()].filter(refused => predicate(refused.definition)).map(refused => refused.job);\n }\n\n /**\n * The ids of the registered jobs whose definition matches — how a surface\n * finds a job by what it is rather than by the file it happens to live in.\n */\n jobIdsWhere(predicate: (definition: CronJobDefinition) => boolean): string[] {\n return [...this.jobs.values()].filter(job => predicate(job.definition)).map(job => job.id);\n }\n\n /**\n * Get a single job status by ID.\n */\n getJob(id: string): CronJobStatus | undefined {\n const job = this.jobs.get(id);\n return job ? this.toStatus(job) : undefined;\n }\n\n /**\n * {@link listJobs}, as the fleet sees it rather than this process alone.\n *\n * Reads the store: every job's enabled state — a pause another replica\n * made — whether another process holds its run lease, and each job's run\n * count and last run from `cron_logs`. The counters in this process's\n * memory count only the runs it made: the `api` role runs nothing and\n * would say 0 runs for a job the worker has run a thousand times, and one\n * of two scheduling replicas never sees the slots the other one claimed.\n *\n * A store that cannot answer leaves this process's own view, with a\n * warning: a listing is not worth failing.\n */\n async fetchJobs(): Promise<CronJobStatus[]> {\n const jobs = [...this.jobs.values()];\n const views = await this.readFleet(jobs);\n return jobs.map(job => this.toStatus(job, views.get(job.id)));\n }\n\n /** {@link getJob}, as {@link fetchJobs} reads it. */\n async fetchJob(id: string): Promise<CronJobStatus | undefined> {\n const job = this.jobs.get(id);\n if (!job) return undefined;\n const views = await this.readFleet([job]);\n return this.toStatus(job, views.get(id));\n }\n\n /**\n * Get log entries for a job.\n */\n getJobLogs(id: string, limit?: number): CronJobLogEntry[] {\n const job = this.jobs.get(id);\n if (!job) return [];\n const logs = [...job.logs].reverse(); // newest first\n return limit ? logs.slice(0, limit) : logs;\n }\n\n /**\n * Get log entries for a job from the database (if store is available).\n * Falls back to in-memory logs if no store is configured, or if the store\n * has none — a run whose row is still being written.\n *\n * Throws when the store cannot read the history. This process's memory is\n * not a stand-in for it: it is empty on the `api` role and after a\n * restart, and holds one replica's runs at most.\n */\n async getJobLogsFromDb(id: string, limit?: number): Promise<CronJobLogEntry[]> {\n if (this.store) {\n const dbLogs = await this.store.fetchLogs(id, limit);\n if (dbLogs.length > 0) return dbLogs;\n }\n // Fallback to in-memory\n return this.getJobLogs(id, limit);\n }\n\n /**\n * Enable or disable a job in this process only. `null` returns it to what\n * its code declares.\n *\n * {@link persistJobEnabled} is what the admin API calls: this alone is\n * forgotten on restart and reaches no other replica.\n */\n setJobEnabled(id: string, enabled: boolean | null): CronJobStatus | undefined {\n const job = this.jobs.get(id);\n if (!job) return undefined;\n\n const effective = enabled ?? this.codeEnabled(job);\n this.applyEnabled(job, effective);\n\n if (effective && this.started) {\n this.scheduleNext(id);\n } else if (!this.shouldArm(job)) {\n this.stopJob(id);\n }\n\n return this.toStatus(job);\n }\n\n /**\n * Enable or disable a job for every process that runs it, and keep it that\n * way across restarts and redeploys: `true` or `false` overrides the code's\n * `enabled`, `null` hands the decision back to it.\n *\n * The override is written to the store first, and only then applied here,\n * so a write that fails throws and changes nothing — a pause that only the\n * replica serving the request would honour is the failure this exists to\n * end. Every scheduler reads the override when a slot comes due, before it\n * claims the slot.\n *\n * Without a store that keeps the state (a driver with no SQL, persistence\n * switched off, a custom store) this is {@link setJobEnabled}: local, and\n * gone on restart.\n */\n async persistJobEnabled(id: string, enabled: boolean | null, updatedBy?: string): Promise<CronJobStatus | undefined> {\n if (!this.jobs.has(id)) return undefined;\n if (this.store?.saveEnabledOverride) {\n await this.store.saveEnabledOverride(id, enabled, updatedBy);\n }\n return this.setJobEnabled(id, enabled);\n }\n\n /**\n * Manually trigger a job execution immediately.\n *\n * Returns `undefined` if the job doesn't exist.\n * If the job is currently executing — here, or on another process that\n * holds its run lease — returns the log entry with a `skipped: true`\n * result rather than running concurrently; {@link isAlreadyExecutingSkip}\n * recognises it.\n */\n async triggerJob(id: string): Promise<CronJobLogEntry | undefined> {\n const job = this.jobs.get(id);\n if (!job) return undefined;\n\n // Concurrency guard — don't run two instances simultaneously\n if (job.executing) {\n logger.warn(`[cron] Skipping manual trigger of \"${id}\" — already executing`);\n return this.recordSkip(job, \"already_executing\", true);\n }\n\n return this.executeJob(job, true);\n }\n\n /**\n * Start a job now and answer as soon as the run has begun, not when it\n * ends — the manual trigger's `?async=1`.\n *\n * The synchronous {@link triggerJob} holds its HTTP request open for the\n * whole run, and a proxy in front of the server (many stop at 60 s) cuts\n * a long job's answer while the run carries on. This resolves once the\n * run lease is held and the handler is about to be called, so a run that\n * cannot start — already executing here or on the lease holder — is still\n * answered as the skip it is. The run itself is tracked like any other:\n * `stop()` waits for it, and its outcome lands in the run history, where\n * the entry carries `manual: true` and the `startedAt` returned here.\n *\n * Returns `undefined` if the job doesn't exist.\n */\n async startJob(id: string): Promise<StartedCronRun | undefined> {\n const job = this.jobs.get(id);\n if (!job) return undefined;\n\n if (job.executing) {\n logger.warn(`[cron] Skipping manual trigger of \"${id}\" — already executing`);\n return { started: false, log: this.recordSkip(job, \"already_executing\", true) };\n }\n\n let onStart!: (startedAt: string) => void;\n const begun = new Promise<string>((resolve) => { onStart = resolve; });\n const run = this.executeJob(job, true, undefined, onStart);\n // Whichever comes first: the handler being called, or the run ending\n // without it (a skip). A run that starts settles `begun` first, since\n // `onStart` is called before the handler is awaited.\n const first = await Promise.race([\n begun.then((startedAt) => ({ startedAt })),\n run.then((log) => ({ log }))\n ]);\n if (\"startedAt\" in first) return { started: true, startedAt: first.startedAt };\n return { started: false, log: first.log };\n }\n\n /**\n * Record a run that did not happen because the previous one had not\n * finished.\n *\n * Written to `cron_logs`, not only to the in-memory ring. An overlap is the\n * signature of a job that has outgrown its schedule — the one thing you want\n * to see in the history rather than infer from a gap in it — and until now\n * the scheduled path left no trace at all beyond a warning in the process\n * log, which is gone by the time anyone asks. The manual path wrote a ring\n * entry that vanished on restart.\n *\n * `success: true` is deliberate: nothing failed. The `result.skipped` flag\n * and the reason are what distinguishes it, and the Studio panel reads them.\n */\n private recordSkip(job: RegisteredJob, reason: string, manual: boolean, runningOn?: string): CronJobLogEntry {\n const now = new Date().toISOString();\n const why = reason === \"already_executing\" ? \"the previous run has not finished\" : reason;\n const logEntry: CronJobLogEntry = {\n jobId: job.id,\n startedAt: now,\n finishedAt: now,\n durationMs: 0,\n success: true,\n result: { skipped: true, reason },\n logs: [`Skipped: ${why}${runningOn ? ` — it is running on ${runningOn}` : \"\"}`],\n manual\n };\n\n job.logs.push(logEntry);\n if (job.logs.length > MAX_LOGS_PER_JOB) job.logs.shift();\n\n // Tracked like a run's own write, so a shutdown does not close the pool\n // under it.\n if (this.store) {\n this.track(this.store.insertLog(logEntry).catch((persistErr) => {\n logger.error(`[cron] Failed to persist skip for \"${job.id}\"`, { error: persistErr });\n }));\n }\n\n return logEntry;\n }\n\n // ─── Internal ────────────────────────────────────────────────────\n\n /** What the job's own definition says, before any override. */\n private codeEnabled(job: RegisteredJob): boolean {\n return job.definition.enabled !== false;\n }\n\n /**\n * Whether the enabled state lives in the store, where every process reads\n * it, rather than in this process alone.\n */\n private sharesEnabledState(): boolean {\n return Boolean(this.store?.fetchJobStates && this.store.saveEnabledOverride);\n }\n\n /**\n * Whether a job gets a timer here. A job paused in this process's memory\n * needs none — nothing but this process can resume it. A job whose state\n * the store keeps does, paused or not: another replica may resume it, and\n * reading the state when its slot comes due is how this one finds out.\n */\n private shouldArm(job: RegisteredJob): boolean {\n return job.enabled || this.sharesEnabledState();\n }\n\n /** Set a job's enabled flag, and its state with it unless a run is in progress. */\n private applyEnabled(job: RegisteredJob, enabled: boolean): void {\n job.enabled = enabled;\n if (job.executing) return;\n if (!enabled) job.state = \"disabled\";\n else if (job.state === \"disabled\") job.state = \"idle\";\n }\n\n /**\n * Whether a job may run now: the store's override when it keeps one, else\n * the code's `enabled`.\n *\n * One query per fire, before the slot is claimed — a paused job does not\n * spend its slot. A store that cannot answer falls back to the code's\n * `enabled`, with a warning: a scheduled run fails open, as it does when\n * the claims table cannot answer, because a broken state table must not\n * silently stop every job.\n */\n private async isEnabledNow(job: RegisteredJob): Promise<boolean> {\n if (!this.store?.fetchJobStates || !this.sharesEnabledState()) return job.enabled;\n try {\n const state = (await this.store.fetchJobStates([job.id])).get(job.id);\n const enabled = state?.enabled ?? this.codeEnabled(job);\n this.applyEnabled(job, enabled);\n return enabled;\n } catch (err) {\n const enabled = this.codeEnabled(job);\n logger.warn(\n `[cron] Could not read the enabled state of \"${job.id}\" — falling back to the code's ` +\n `enabled (${enabled}); a pause made from the admin API is not being honoured`,\n { error: err }\n );\n return enabled;\n }\n }\n\n /**\n * How long a run's lease lasts: the run's timeout and a grace, so that a\n * crashed holder frees the job once its run would have been aborted\n * anyway. No timeout gets {@link MAX_UNBOUNDED_LEASE_SECONDS}.\n */\n private leaseSeconds(job: RegisteredJob): number {\n const timeout = job.definition.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;\n return Number.isFinite(timeout) ? timeout + LEASE_GRACE_SECONDS : MAX_UNBOUNDED_LEASE_SECONDS;\n }\n\n /**\n * Take the job's run lease, the cross-process half of \"already\n * executing\". A store without leases, or one that cannot answer, lets the\n * run go ahead unleased — with a warning in the second case — the same way\n * a claim that cannot answer does.\n */\n private async acquireLease(job: RegisteredJob): Promise<LeaseOutcome> {\n if (!this.store?.tryAcquireRunLease) return { acquired: true };\n const token = `${this.instanceLabel}#${randomUUID().slice(0, 8)}`;\n try {\n const lease = await this.store.tryAcquireRunLease(job.id, token, this.leaseSeconds(job));\n return lease.acquired ? { acquired: true, token } : lease;\n } catch (err) {\n logger.warn(\n `[cron] Could not take the run lease for \"${job.id}\" — running without it, ` +\n \"so another process may run it at the same time\",\n { error: err }\n );\n return { acquired: true };\n }\n }\n\n /** Release a lease this run took. A release that fails leaves it to lapse. */\n private async releaseLease(job: RegisteredJob, token: string): Promise<void> {\n try {\n await this.store?.releaseRunLease?.(job.id, token);\n } catch (err) {\n logger.warn(\n `[cron] Could not release the run lease for \"${job.id}\" — it lapses on its own ` +\n `within ${this.leaseSeconds(job)}s`,\n { error: err }\n );\n }\n }\n\n /**\n * What the store says about `jobs` beyond this process — see\n * {@link fetchJobs}. Applies the enabled state it reads, and returns the\n * rest as a view for {@link toStatus}. Never throws.\n */\n private async readFleet(jobs: RegisteredJob[]): Promise<Map<string, FleetView>> {\n const views = new Map<string, FleetView>();\n const viewOf = (id: string): FleetView => {\n let view = views.get(id);\n if (!view) {\n view = {};\n views.set(id, view);\n }\n return view;\n };\n const store = this.store;\n const ids = jobs.map(job => job.id);\n\n if (store?.fetchJobStates && this.sharesEnabledState() && ids.length > 0) {\n try {\n const states = await store.fetchJobStates(ids);\n for (const job of jobs) {\n const state = states.get(job.id);\n this.applyEnabled(job, state?.enabled ?? this.codeEnabled(job));\n if (state?.runningBy && !job.executing) viewOf(job.id).runningElsewhere = true;\n }\n } catch (err) {\n logger.warn(\"[cron] Could not read the jobs' shared state — listing what this process knows\", { error: err });\n }\n }\n\n // Only where nothing is scheduled: a started scheduler has its own next\n // slots.\n if (!this.started) {\n const now = new Date();\n for (const job of jobs) {\n try {\n viewOf(job.id).nextRunAt = this.listedNextRun(job, now);\n } catch {\n // A schedule with no reachable slot has no next run to show.\n }\n }\n }\n // Wherever this process stands. Its own counters are seeded from the\n // store once, at start, and after that count only its own runs:\n // with two replicas scheduling, a slot the other one claimed never\n // reached them, and the card said \"idle, 0 runs\" over a history that\n // listed the failure.\n if (store?.fetchRunSummaries && ids.length > 0) {\n try {\n const summaries = await store.fetchRunSummaries(ids);\n for (const [id, summary] of summaries) viewOf(id).summary = summary;\n } catch (err) {\n logger.warn(\"[cron] Could not read the jobs' run history — listing what this process knows\", { error: err });\n }\n }\n return views;\n }\n\n /**\n * The next slot of `job` after `now`, for a listing on a process whose\n * scheduler is not started — the `api` role, which Studio's Cron panel\n * polls every 15 seconds.\n *\n * Cached on the job. The key is the job's schedule and zone (a re-register\n * replaces the job, and with it the cache); the entry holds while\n * `computedAt <= now < slot`. That is the same answer, not an\n * approximation: the search found no matching minute between\n * `computedAt`'s next minute and `slot`, so from any later instant before\n * `slot` it lands on `slot` again. A clock that moves back, or reaching the\n * slot, recomputes. The cache holds a pure function of the schedule, so\n * there is nothing user- or role-scoped in it.\n */\n private listedNextRun(job: RegisteredJob, now: Date): Date {\n const { schedule, timezone } = job.definition;\n const nowMs = now.getTime();\n const cached = job.listedSlot;\n if (\n cached\n && cached.schedule === schedule\n && cached.timezone === timezone\n && cached.computedAt <= nowMs\n && nowMs < cached.slot.getTime()\n ) {\n return cached.slot;\n }\n const slot = parseCronExpression(schedule, now, timezone);\n job.listedSlot = { schedule, timezone, computedAt: nowMs, slot };\n return slot;\n }\n\n /**\n * Warn once at start when the process looks like it is running on a\n * platform that freezes or evicts instances between requests, where the\n * in-process timers this scheduler relies on never fire.\n *\n * Advisory only: any failure here is swallowed so a detection bug can\n * never take a production boot down.\n */\n private warnIfScaleToZero(): void {\n try {\n const warning = buildScaleToZeroWarning(\n [...this.jobs.values()].map((job) => ({ id: job.id, enabled: job.enabled }))\n );\n if (warning) {\n logger.warn(warning.message, warning.data);\n }\n } catch {\n // Never let the advisory check affect startup.\n }\n }\n\n /**\n * Schedule the next execution for a job.\n *\n * Safety guarantees:\n * 1. Clears any existing timer first (prevents leaked/duplicate timers)\n * 2. Enforces a minimum delay to prevent tight loops from jitter\n * 3. Unref's the timer so it doesn't prevent process exit\n * 4. Re-checks enabled & started state before executing\n * 5. Concurrency guard prevents overlapping handler executions\n */\n private scheduleNext(id: string): void {\n const job = this.jobs.get(id);\n if (!job || !this.started || !this.shouldArm(job)) return;\n\n // Clear any previously scheduled timer to prevent double-firing\n this.stopJob(id);\n\n try {\n const now = new Date();\n const nextRun = parseCronExpression(job.definition.schedule, now, job.definition.timezone);\n job.nextRunAt = nextRun;\n\n const rawDelay = nextRun.getTime() - now.getTime();\n // Enforce a minimum delay to prevent tight re-execution loops\n // from event loop jitter or near-zero setTimeout drift\n const delay = Math.max(rawDelay, MIN_SCHEDULE_INTERVAL_MS);\n\n // A slot past the 32-bit timer ceiling cannot be armed directly:\n // setTimeout would clamp it to 1ms and fire at once, and since the\n // slot is already claimed by then, every wake re-schedules the same\n // overflowing delay — a permanent hot loop, not a late job. Sleep\n // to the ceiling and re-derive the delay on waking instead; the\n // cron expression stays the source of truth across the hops.\n if (delay > MAX_TIMER_DELAY_MS) {\n const hop = setTimeout(() => {\n if (this.started && this.shouldArm(job)) this.scheduleNext(id);\n }, MAX_TIMER_DELAY_MS);\n if (hop && typeof hop === \"object\" && \"unref\" in hop) {\n hop.unref();\n }\n job.timerId = hop;\n return;\n }\n\n const timer = setTimeout(async () => {\n // Re-check state: the scheduler may have been stopped between\n // when we scheduled and when we fire\n if (!this.started) return;\n\n // A timer can wake before its slot: a delay past the 32-bit\n // ceiling, a clock stepped backwards by NTP, a VM resuming from\n // suspend. Claiming on an early wake is unrecoverable — claims\n // are permanent, so the slot would be burned and the real run\n // silently skipped when it came due. Re-derive from the wall\n // clock and re-arm instead; only the fire that is genuinely due\n // may claim.\n if (Date.now() < nextRun.getTime()) {\n this.scheduleNext(id);\n return;\n }\n\n // Paused or resumed — perhaps by another replica, perhaps\n // before this process started. Asked of the store at every\n // fire, and before the claim, so a paused job leaves its slot\n // unspent.\n if (!(await this.isEnabledNow(job))) {\n if (this.started && this.shouldArm(job)) this.scheduleNext(id);\n return;\n }\n if (!this.started) return;\n\n // Concurrency guard: if somehow we're already executing, skip\n if (job.executing) {\n logger.warn(`[cron] Skipping scheduled run of \"${id}\" — still executing from previous run`);\n // Recorded as well as logged: a job that keeps overlapping\n // has outgrown its schedule, and that is visible in the run\n // history or nowhere.\n this.recordSkip(job, \"already_executing\", false);\n // Re-schedule to try again later\n this.scheduleNext(id);\n return;\n }\n\n // Cross-instance guard: claim the scheduled slot in the store.\n // The slot is the scheduled fire time — deterministic across\n // instances — so exactly one instance wins each (job, slot) pair.\n // A store without tryClaimRun (pre-claims custom implementation)\n // runs uncoordinated; a throwing store fails open — either way\n // this callback must never reject, or the job would silently\n // stop rescheduling.\n if (this.store?.tryClaimRun) {\n let claimed = true;\n try {\n claimed = await this.store.tryClaimRun(id, nextRun.toISOString());\n } catch (err) {\n logger.warn(`[cron] Claim check threw for \"${id}\" — running uncoordinated`, { error: err });\n }\n if (!claimed) {\n logger.info(`[cron] Slot ${nextRun.toISOString()} for \"${id}\" claimed by another instance — skipping`);\n if (this.started && this.shouldArm(job)) {\n this.scheduleNext(id);\n }\n return;\n }\n }\n\n // Takes the run lease: a manual trigger in progress on another\n // process — the api role's, say — turns this slot into a\n // recorded skip rather than a second run beside it.\n await this.executeJob(job, false);\n\n // Schedule the next tick (only if still started + armed)\n if (this.started && this.shouldArm(job)) {\n this.scheduleNext(id);\n }\n }, delay);\n\n // Unref the timer so it doesn't prevent Node.js from exiting\n // during graceful shutdown\n if (timer && typeof timer === \"object\" && \"unref\" in timer) {\n timer.unref();\n }\n\n job.timerId = timer;\n } catch (err: unknown) {\n logger.error(`[cron] Failed to schedule \"${id}\"`, { error: err });\n job.state = \"error\";\n job.lastError = err instanceof Error ? err.message : String(err);\n }\n }\n\n /**\n * Run any slot that elapsed while no instance was holding a timer for it.\n *\n * Only jobs that opted in via `catchUpWindowSeconds` are considered, and\n * only their single most recent missed slot — see the field's docs for why\n * both limits are deliberate.\n *\n * The claim is what makes this safe. In the ordinary case — an instance\n * restarting minutes after a slot ran normally — the most recent slot is\n * already claimed, so this costs one `tryClaimRun` per job per boot and\n * does nothing. A slot is only executed when no instance, past or present,\n * ever claimed it.\n *\n * Never throws: a failure here must not take down a scheduler that is\n * otherwise ticking correctly.\n */\n private async catchUpMissedSlots(): Promise<void> {\n // Every job with a window whose state the store may override, not only\n // the ones enabled here: a job the code disables can be resumed from\n // the admin API, and one it enables can be paused there. Each is asked\n // below, before its claim.\n const candidates = [...this.jobs.values()].filter(\n job => this.shouldArm(job) && (job.definition.catchUpWindowSeconds ?? 0) > 0\n );\n if (candidates.length === 0) return;\n\n // A claims-capable store is the whole safety mechanism. Without one,\n // every boot would look like \"this slot never ran\" and an instance\n // recycled twice an hour would re-run the same hourly job twice an\n // hour. Refusing to catch up is the correct degradation.\n if (!this.store?.tryClaimRun) {\n logger.warn(\n `[cron] Catch-up is configured on ${candidates.length} job(s) but no claims-capable store is attached — skipping. ` +\n \"Without claims a restart cannot tell an unrun slot from one the previous instance already ran.\"\n );\n return;\n }\n\n for (const job of candidates) {\n try {\n if (!this.started || job.executing) continue;\n // The persisted pause outlives the deploy that is catching up.\n if (!(await this.isEnabledNow(job))) continue;\n if (!this.started || job.executing) continue;\n\n // Read per job, not once for the pass: the jobs ahead of this\n // one ran their catch-ups first, and this job's own timer may\n // have fired newer slots meanwhile. Its most recent slot is the\n // one as of now, or a stale one runs after newer ones already did.\n const now = new Date();\n const windowSeconds = job.definition.catchUpWindowSeconds!;\n const from = new Date(now.getTime() - windowSeconds * 1000);\n const slot = findMostRecentSlot(job.definition.schedule, from, now, job.definition.timezone);\n if (!slot) continue;\n\n const slotIso = slot.toISOString();\n\n // Same key the scheduled path claims with, so a slot that fired\n // normally is already taken and this is a no-op.\n let claimed: boolean;\n try {\n claimed = await this.store.tryClaimRun(job.id, slotIso);\n } catch (err) {\n // Fail closed, unlike the scheduled path. A missed slot is\n // a recovery, not an obligation — running it against a\n // store that cannot tell us whether it already ran risks a\n // duplicate on every boot.\n logger.warn(`[cron] Catch-up claim threw for \"${job.id}\" — skipping catch-up`, { error: err });\n continue;\n }\n\n if (!claimed) continue;\n\n const lateBy = Math.round((now.getTime() - slot.getTime()) / 1000);\n logger.info(`[cron] Catching up missed slot ${slotIso} for \"${job.id}\" (${lateBy}s late)`);\n\n await this.executeJob(job, false, `⏰ Catch-up run for missed slot ${slotIso} (${lateBy}s late)`);\n } catch (err) {\n logger.error(`[cron] Catch-up failed for \"${job.id}\"`, { error: err });\n }\n }\n }\n\n /**\n * Stop a single job's timer and clear its next run state.\n */\n private stopJob(id: string): void {\n const job = this.jobs.get(id);\n if (job?.timerId) {\n clearTimeout(job.timerId);\n job.timerId = undefined;\n job.nextRunAt = undefined;\n }\n }\n\n /**\n * Execute a job's handler with full isolation and safety.\n *\n * - Sets a concurrency flag to prevent overlapping runs\n * - Wraps handler in a timeout race\n * - Captures all logs, errors, and results\n * - Persists to store (non-blocking) if available\n * - Always restores state even on catastrophic errors\n */\n private executeJob(\n job: RegisteredJob,\n manual: boolean,\n seedLog?: string,\n onStart?: (startedAt: string) => void\n ): Promise<CronJobLogEntry> {\n // Aborted when the run is over before its handler is: the timeout\n // below, or `stop()` giving up on it. Without it the timeout only\n // stopped the scheduler waiting: the handler's `fetch` kept its socket,\n // so a job whose timeout matches its interval leaked one abandoned\n // request per tick while every run was already marked failed.\n const abort = new AbortController();\n this.runControllers.add(abort);\n const run = this.runJob(job, manual, abort, seedLog, onStart);\n this.track(run);\n return run.finally(() => {\n this.runControllers.delete(abort);\n });\n }\n\n /** Hold `stop()` until `work` settles. */\n private track(work: Promise<unknown>): void {\n this.inFlight.add(work);\n const release = () => { this.inFlight.delete(work); };\n work.then(release, release);\n }\n\n private async runJob(\n job: RegisteredJob,\n manual: boolean,\n abort: AbortController,\n seedLog?: string,\n onStart?: (startedAt: string) => void\n ): Promise<CronJobLogEntry> {\n // Checked here as well as by each caller, because each caller awaits\n // something (a claim, a state read) between its own check and this.\n if (job.executing) {\n return this.recordSkip(job, \"already_executing\", manual);\n }\n // Set executing flag — prevents concurrent runs. Taken before the lease\n // is awaited, so a second trigger on this process cannot slip in.\n job.executing = true;\n\n // The lease is what keeps the other processes off: the worker's\n // scheduled run and the api role's manual trigger never saw each\n // other's in-process flag.\n const lease = await this.acquireLease(job);\n if (!lease.acquired) {\n job.executing = false;\n logger.warn(`[cron] Skipping ${manual ? \"manual trigger\" : \"scheduled run\"} of \"${job.id}\" — it is running on ${lease.holder ?? \"another process\"}`);\n return this.recordSkip(job, \"already_executing\", manual, lease.holder ?? \"another process\");\n }\n\n const startedAt = new Date();\n // A caller-supplied first line, stored with the run's own output. A\n // catch-up uses it to say so in the persisted log, where an operator\n // reading `cron_logs` will actually see it — `manual` is the only other\n // provenance the entry carries, and a catch-up is not manual.\n const capturedLogs = createLogCapture(seedLog || undefined);\n\n const ctx: CronJobContext = {\n jobId: job.id,\n scheduledAt: startedAt,\n signal: abort.signal,\n log: (...args: unknown[]) => {\n const line = args.map((a) =>\n typeof a === \"string\" ? a : JSON.stringify(a)\n ).join(\" \");\n // Capped — see `MAX_CAPTURED_LOG_LINES`. The process log below\n // is not: it gets every line.\n capturedLogs.add(line);\n // Also to the process log. `cron_logs` is behind the admin\n // API, so a line that went only there was missing from the\n // platform's logs, which is where an operator looks when a\n // run goes wrong. The values are redacted on the way: a\n // stringified object reaches the logger as text, and the\n // logger's own pass over the message only removes `Failed\n // query:` spans from it.\n logger.info(\n args.map((a) => typeof a === \"string\" ? a : stringifyForLog(a)).join(\" \"),\n { cron: job.id }\n );\n },\n // `rebase`, and only `rebase`: it matches the singleton import and\n // `defineFunction`'s context. The old `client` alias re-exposed\n // `client.data`, the name `RebaseServerClient` deliberately omits so\n // that the RLS-bypassing plane is spelled `dataAsAdmin` everywhere.\n rebase: this.client!\n };\n\n job.state = \"running\";\n job.lastRunAt = startedAt;\n job.totalRuns++;\n onStart?.(startedAt.toISOString());\n\n let success = true;\n let error: string | undefined;\n let result: unknown;\n\n // The run ends when the handler settles or when `abort` fires,\n // whichever is first — so an abort ends the run even for a handler\n // that ignores its signal, and the run is recorded rather than left\n // \"running\" forever.\n const aborted = new Promise<never>((_, reject) => {\n const end = () => reject(abort.signal.reason);\n if (abort.signal.aborted) end();\n else abort.signal.addEventListener(\"abort\", end, { once: true });\n });\n // Handled here as well as by the race: a handler that throws before\n // the race is entered leaves nothing else listening.\n aborted.catch(() => undefined);\n\n try {\n // Race with timeout. Past the 32-bit timer ceiling a plain\n // setTimeout fires after 1ms, so a month-long timeout would fail\n // every run at once; Infinity is no timeout at all.\n const timeout = (job.definition.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1000;\n const cancelTimeout = Number.isFinite(timeout)\n ? setLongTimeout(\n () => abort.abort(new Error(`Cron job \"${job.id}\" timed out after ${timeout}ms`)),\n timeout\n )\n : undefined;\n\n try {\n result = await Promise.race([Promise.resolve(job.definition.handler(ctx)), aborted]);\n } finally {\n cancelTimeout?.();\n }\n } catch (err: unknown) {\n success = false;\n // Redacted at the point of capture, not just on the way to the log:\n // this string is persisted into `cron_logs` and rendered in the\n // Studio cron panel, and a job that fails on a query would\n // otherwise store `Failed query: <sql>\\nparams: <values>` — the\n // statement and every bound value — in a table, indefinitely.\n error = redactSensitiveText(err instanceof Error ? err.message : String(err));\n job.totalFailures++;\n } finally {\n // The lease before the flag: in between, a trigger on this process\n // would pass the flag and then find its own process's lease held.\n if (lease.token) await this.releaseLease(job, lease.token);\n // Always clear executing flag — even on catastrophic errors\n job.executing = false;\n }\n\n const finishedAt = new Date();\n const durationMs = finishedAt.getTime() - startedAt.getTime();\n\n job.state = success ? (job.enabled ? \"idle\" : \"disabled\") : \"error\";\n job.lastDurationMs = durationMs;\n job.lastError = error;\n\n const logEntry: CronJobLogEntry = {\n jobId: job.id,\n startedAt: startedAt.toISOString(),\n finishedAt: finishedAt.toISOString(),\n durationMs,\n success,\n error,\n result: result !== undefined ? result : undefined,\n logs: capturedLogs.close(),\n manual\n };\n\n // Push to ring buffer\n job.logs.push(logEntry);\n if (job.logs.length > MAX_LOGS_PER_JOB) {\n job.logs.shift();\n }\n\n // Persist to database (non-blocking for the run, but tracked, so a\n // shutdown does not close the pool under the write)\n if (this.store) {\n this.track(this.store.insertLog(logEntry).catch((persistErr) => {\n logger.error(`[cron] Failed to persist log for \"${job.id}\"`, { error: persistErr });\n }));\n }\n\n if (success) {\n logger.info(`✅ [cron] \"${job.id}\" completed in ${durationMs}ms`);\n } else {\n logger.error(`❌ [cron] \"${job.id}\" failed in ${durationMs}ms: ${error}`);\n }\n\n return logEntry;\n }\n\n /**\n * A job's status: this process's own record, overlaid with what `view`\n * read from the store. A paused job shows no next run, even where its\n * timer stays armed to read the state again at that slot.\n */\n private toStatus(job: RegisteredJob, view: FleetView = {}): CronJobStatus {\n const summary = view.summary;\n const nextRunAt = job.enabled ? (job.nextRunAt ?? view.nextRunAt) : undefined;\n let state = job.state;\n if (!job.executing) {\n if (view.runningElsewhere) state = \"running\";\n else if (summary && job.enabled) state = summary.lastSuccess === false ? \"error\" : \"idle\";\n }\n return {\n id: job.id,\n // Same fallback the two `listJobs` paths already applied: `name` is\n // optional and the id is the file's own name.\n name: job.definition.name ?? job.id,\n description: job.definition.description,\n schedule: job.definition.schedule,\n enabled: job.enabled,\n state,\n lastRunAt: summary ? summary.lastRunAt : job.lastRunAt?.toISOString(),\n nextRunAt: nextRunAt?.toISOString(),\n lastDurationMs: summary ? summary.lastDurationMs : job.lastDurationMs,\n lastError: summary ? (summary.lastSuccess === false ? summary.lastError : undefined) : job.lastError,\n totalRuns: summary ? summary.totalRuns : job.totalRuns,\n totalFailures: summary ? summary.totalFailures : job.totalFailures\n };\n }\n}\n"],"mappings":"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"}
|