@stacksjs/ts-cloud 0.7.56 → 0.7.57

package/dist/jobs/adapters.d.ts

@@ -0,0 +1,23 @@
+import type { JsonValue } from '../control-plane';
+import type { ScheduledJob } from './model';
+export interface JobProviderCapability {
+    provider: ScheduledJob['provider'];
+    supported: boolean;
+    features: {
+        timezone: boolean;
+        flexibleWindow: boolean;
+        catchUp: boolean;
+        replaceOverlap: boolean;
+    };
+    notes: string[];
+}
+export declare function jobProviderCapability(job: Pick<ScheduledJob, 'provider' | 'expression' | 'flexibleMinutes' | 'missedRunPolicy' | 'overlapPolicy'>): JobProviderCapability;
+export declare function renderServerCron(job: ScheduledJob): {
+    path: string;
+    content: string;
+};
+export declare function eventBridgeScheduleInput(job: ScheduledJob): Record<string, JsonValue>;
+export declare function reconcileJobObservation(job: ScheduledJob, observed: Record<string, JsonValue> | undefined): {
+    status: ScheduledJob['reconciliationStatus'];
+    observedState: Record<string, JsonValue>;
+};

package/dist/jobs/index.d.ts

@@ -0,0 +1,7 @@
+export * from './model';
+export * from './adapters';
+export * from './provider-adapters';
+export * from './reconcile';
+export * from './schedule';
+export * from './service';
+export * from './store';

package/dist/jobs/jobs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/jobs/model.d.ts

@@ -0,0 +1,100 @@
+import type { JsonValue } from '../control-plane';
+export type JobProvider = 'server' | 'eventbridge' | 'lambda' | 'platform';
+export type JobTrigger = 'scheduled' | 'manual' | 'catch_up' | 'external' | 'retry';
+export type JobExecutionStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'skipped' | 'dead';
+export type ReconciliationStatus = 'pending' | 'in_sync' | 'drifted' | 'unsupported' | 'unavailable';
+export interface JobTarget {
+    kind: 'dashboard_operation' | 'serverless_scheduler' | 'lambda' | 'platform';
+    operationId?: string;
+    action?: string;
+    functionName?: string;
+    platformOperation?: string;
+}
+export interface ScheduledJob {
+    id: string;
+    organizationId: string;
+    projectId: string;
+    environmentId?: string;
+    resourceId?: string;
+    name: string;
+    provider: JobProvider;
+    expression: string;
+    normalizedExpression: string;
+    timezone: string;
+    startsAt?: string;
+    endsAt?: string;
+    flexibleMinutes: number;
+    target: JobTarget;
+    payloadRefs: Record<string, JsonValue>;
+    missedRunPolicy: 'skip' | 'catch_up';
+    overlapPolicy: 'allow' | 'forbid' | 'replace';
+    retryPolicy: {
+        maxAttempts: number;
+        backoffSeconds: number;
+        deadLetterRef?: string;
+    };
+    timeoutSeconds: number;
+    enabled: boolean;
+    origin: 'managed' | 'config' | 'external';
+    sourceKey?: string;
+    ownerActorId?: string;
+    observedState: Record<string, JsonValue>;
+    reconciliationStatus: ReconciliationStatus;
+    nextRunAt?: string;
+    lastScheduledFor?: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface JobExecution {
+    id: string;
+    jobId: string;
+    operationId?: string;
+    trigger: JobTrigger;
+    scheduledFor: string;
+    idempotencyKey: string;
+    status: JobExecutionStatus;
+    attempt: number;
+    startedAt?: string;
+    finishedAt?: string;
+    output: Record<string, JsonValue>;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface WorkerDefinition {
+    id: string;
+    organizationId: string;
+    projectId: string;
+    environmentId?: string;
+    resourceId?: string;
+    name: string;
+    provider: 'systemd' | 'ecs' | 'lambda';
+    queue: string;
+    processes: number;
+    timeoutSeconds: number;
+    restartPolicy: 'always' | 'on_failure' | 'never';
+    target: Record<string, JsonValue>;
+    enabled: boolean;
+    origin: 'managed' | 'config' | 'external';
+    sourceKey?: string;
+    ownerActorId?: string;
+    observedState: Record<string, JsonValue>;
+    reconciliationStatus: ReconciliationStatus;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SchedulePreview {
+    original: string;
+    normalized: string;
+    kind: 'cron' | 'rate';
+    timezone: string;
+    description: string;
+    nextRuns: string[];
+    capabilities: {
+        server: boolean;
+        eventbridge: boolean;
+        notes: string[];
+    };
+}

package/dist/jobs/provider-adapters.d.ts

@@ -0,0 +1,49 @@
+import type { JsonValue } from '../control-plane';
+import type { JobProvider, ScheduledJob } from './model';
+import { JobStore } from './store';
+export type JobDesiredState = Record<string, JsonValue>;
+export interface JobProviderAdapter {
+    readonly provider: JobProvider;
+    observe(job: ScheduledJob): Promise<JobDesiredState | undefined>;
+    apply(job: ScheduledJob, desired: JobDesiredState): Promise<void>;
+    remove(job: ScheduledJob): Promise<void>;
+    matches(desired: JobDesiredState, observed: JobDesiredState): boolean;
+}
+export interface ServerCronTransport {
+    read(path: string): Promise<string | undefined>;
+    writeRootOwned(path: string, content: string): Promise<void>;
+    removeRootOwned(path: string): Promise<void>;
+}
+export interface EventBridgeScheduleTransport {
+    get(name: string): Promise<JobDesiredState | undefined>;
+    put(input: JobDesiredState): Promise<void>;
+    remove(name: string): Promise<void>;
+}
+declare function desiredState(job: ScheduledJob): JobDesiredState;
+export declare class ServerCronJobAdapter implements JobProviderAdapter {
+    private readonly transport;
+    readonly provider: 'server';
+    constructor(transport: ServerCronTransport);
+    observe(job: ScheduledJob): Promise<JobDesiredState | undefined>;
+    apply(job: ScheduledJob, desired: JobDesiredState): Promise<void>;
+    remove(job: ScheduledJob): Promise<void>;
+    matches(desired: JobDesiredState, observed: JobDesiredState): boolean;
+}
+export declare class EventBridgeJobAdapter implements JobProviderAdapter {
+    private readonly transport;
+    readonly provider: 'eventbridge';
+    constructor(transport: EventBridgeScheduleTransport);
+    observe(job: ScheduledJob): Promise<JobDesiredState | undefined>;
+    apply(_job: ScheduledJob, desired: JobDesiredState): Promise<void>;
+    remove(job: ScheduledJob): Promise<void>;
+    matches(desired: JobDesiredState, observed: JobDesiredState): boolean;
+}
+export declare class JobProviderReconciler {
+    private readonly store;
+    constructor(store: JobStore);
+    reconcile(job: ScheduledJob, adapter: JobProviderAdapter, options?: {
+        apply?: boolean;
+    }): Promise<ScheduledJob>;
+    remove(job: ScheduledJob, adapter: JobProviderAdapter): Promise<void>;
+}
+export { desiredState as desiredJobProviderState };

package/dist/jobs/reconcile.d.ts

@@ -0,0 +1,19 @@
+import type { CloudConfig } from '@ts-cloud/core';
+import type { ControlPlaneEnvironment, ControlPlaneOrganization, ControlPlaneProject, ControlPlaneResource } from '../control-plane';
+import { JobStore } from './store';
+interface ReconciliationScope {
+    organization: ControlPlaneOrganization;
+    project: ControlPlaneProject;
+    environment: ControlPlaneEnvironment;
+    resources: ControlPlaneResource[];
+}
+/**
+ * Import declarative schedules and workers without deleting records that disappear
+ * from configuration. Missing definitions are marked drifted for an explicit review.
+ */
+export declare function synchronizeConfiguredJobs(store: JobStore, config: CloudConfig, scope: ReconciliationScope): {
+    jobs: number;
+    workers: number;
+    drifted: number;
+};
+export {};

package/dist/jobs/schedule.d.ts

@@ -0,0 +1,9 @@
+import type { SchedulePreview } from './model';
+export declare function normalizeScheduleExpression(value: string): {
+    original: string;
+    normalized: string;
+    kind: 'cron' | 'rate';
+    description: string;
+};
+export declare function nextScheduleRuns(expression: string, zone: string, from?: Date, count?: number): string[];
+export declare function previewSchedule(expression: string, zone?: string, from?: Date, count?: number): SchedulePreview;

package/dist/jobs/service.d.ts

@@ -0,0 +1,30 @@
+import type { JsonValue } from '../control-plane';
+import type { QueueExecutionContext, QueueOperationHandler } from '../queue';
+import type { JobExecution, JobTarget, JobTrigger, ScheduledJob } from './model';
+import { DurableOperationQueue } from '../queue';
+import { JobStore } from './store';
+export interface JobExecutorResult {
+    ok: boolean;
+    output?: Record<string, JsonValue>;
+    stdout?: string;
+    stderr?: string;
+    retryable?: boolean;
+}
+export type JobExecutor = (job: ScheduledJob, target: JobTarget, context: QueueExecutionContext) => Promise<JobExecutorResult>;
+export declare class JobService {
+    readonly store: JobStore;
+    readonly queue: DurableOperationQueue;
+    constructor(store: JobStore, options?: {
+        queue?: DurableOperationQueue;
+    });
+    enqueue(job: ScheduledJob, input: {
+        trigger: JobTrigger;
+        scheduledFor?: string;
+        actorId?: string;
+    }): JobExecution;
+    tick(at?: Date): JobExecution[];
+}
+export declare function createJobQueueHandlers(input: {
+    store: JobStore;
+    executor: JobExecutor;
+}): Record<string, QueueOperationHandler>;

package/dist/jobs/store.d.ts

@@ -0,0 +1,48 @@
+import type { ControlPlaneStore, JsonValue } from '../control-plane';
+import type { JobExecution, JobExecutionStatus, ReconciliationStatus, ScheduledJob, WorkerDefinition } from './model';
+export declare class JobStore {
+    readonly controlPlane: ControlPlaneStore;
+    private readonly options;
+    constructor(controlPlane: ControlPlaneStore, options?: {
+        now?: () => Date;
+    });
+    now(): Date;
+    create(input: Omit<ScheduledJob, 'id' | 'normalizedExpression' | 'nextRunAt' | 'lastScheduledFor' | 'version' | 'createdAt' | 'updatedAt'>): ScheduledJob;
+    get(id: string): ScheduledJob | undefined;
+    getBySource(projectId: string, environmentId: string | undefined, sourceKey: string): ScheduledJob | undefined;
+    list(projectId: string, input?: {
+        environmentId?: string;
+        resourceIds?: string[];
+        enabled?: boolean;
+    }): ScheduledJob[];
+    setEnabled(id: string, enabled: boolean): ScheduledJob;
+    updateSchedule(id: string, input: {
+        expression?: string;
+        timezone?: string;
+        missedRunPolicy?: ScheduledJob['missedRunPolicy'];
+        overlapPolicy?: ScheduledJob['overlapPolicy'];
+        timeoutSeconds?: number;
+    }): ScheduledJob;
+    remove(id: string): void;
+    markScheduled(id: string, scheduledFor: string, nextRunAt?: string): void;
+    reconcile(id: string, status: ReconciliationStatus, observedState: Record<string, JsonValue>): ScheduledJob;
+    upsertConfigJob(input: Omit<ScheduledJob, 'id' | 'normalizedExpression' | 'nextRunAt' | 'lastScheduledFor' | 'version' | 'createdAt' | 'updatedAt'> & {
+        sourceKey: string;
+    }): ScheduledJob;
+    due(at?: string): ScheduledJob[];
+    createExecution(input: Omit<JobExecution, 'id' | 'attempt' | 'startedAt' | 'finishedAt' | 'createdAt' | 'updatedAt'>): JobExecution;
+    getExecution(id: string): JobExecution | undefined;
+    listExecutions(jobId: string, limit?: number): JobExecution[];
+    activeExecution(jobId: string): JobExecution | undefined;
+    attachOperation(id: string, operationId: string): JobExecution;
+    transitionExecution(id: string, status: JobExecutionStatus, input?: {
+        attempt?: number;
+        output?: Record<string, JsonValue>;
+        error?: string;
+    }): JobExecution;
+    upsertWorker(input: Omit<WorkerDefinition, 'id' | 'version' | 'createdAt' | 'updatedAt'>): WorkerDefinition;
+    getWorker(id: string): WorkerDefinition | undefined;
+    listWorkers(projectId: string, environmentId?: string): WorkerDefinition[];
+    setWorkerProcesses(id: string, processes: number): WorkerDefinition;
+    reconcileWorker(id: string, status: ReconciliationStatus, observedState: Record<string, JsonValue>): WorkerDefinition;
+}

package/dist/maintenance/drivers.d.ts

@@ -0,0 +1,117 @@
+import type { ControlPlaneStore } from '../control-plane';
+import type { CleanupCandidate, CleanupDriver, CleanupPlan, DisasterRecoveryDrill, DisasterRecoveryDriver, PlatformMaintenanceDriver, PlatformUpdateDocument, UpgradeTarget } from './types';
+export interface PlatformMaintenanceTransport {
+    download(input: {
+        target: string;
+        url: string;
+        signal: AbortSignal;
+    }): Promise<{
+        path: string;
+        sha256: string;
+    }>;
+    install(input: {
+        target: string;
+        path: string;
+        version: string;
+        signal: AbortSignal;
+    }): Promise<void>;
+    health(input: {
+        target: string;
+        gate: Record<string, unknown>;
+    }): Promise<{
+        healthy: boolean;
+        evidence: Record<string, any>;
+    }>;
+    rollback(input: {
+        target: string;
+        version: string;
+        signal: AbortSignal;
+    }): Promise<void>;
+}
+export declare class TransportPlatformMaintenanceDriver implements PlatformMaintenanceDriver {
+    private transport;
+    constructor(transport: PlatformMaintenanceTransport);
+    download(input: {
+        target: UpgradeTarget;
+        artifact: PlatformUpdateDocument['artifacts'][number];
+        signal: AbortSignal;
+    }): Promise<{
+        path: string;
+        sha256: string;
+    }>;
+    install(input: {
+        target: UpgradeTarget;
+        path: string;
+        version: string;
+        signal: AbortSignal;
+    }): Promise<void>;
+    health(input: {
+        target: UpgradeTarget;
+        gate: Record<string, any>;
+    }): Promise<{
+        healthy: boolean;
+        evidence: Record<string, any>;
+    }>;
+    rollback(input: {
+        target: UpgradeTarget;
+        version: string;
+        signal: AbortSignal;
+    }): Promise<void>;
+}
+export declare class ControlPlaneCleanupDriver implements CleanupDriver {
+    readonly kind: CleanupPlan['kind'];
+    private control;
+    private projectId;
+    private organizationId;
+    constructor(kind: CleanupPlan['kind'], control: ControlPlaneStore, projectId: string, organizationId: string);
+    discover(criteria: CleanupPlan['criteria']): Promise<CleanupCandidate[]>;
+    remove(candidate: CleanupCandidate): Promise<void>;
+}
+export interface DisasterRecoveryTransport {
+    restore(input: {
+        scenario: DisasterRecoveryDrill['scenario'];
+        drill: DisasterRecoveryDrill;
+        signal: AbortSignal;
+    }): Promise<{
+        target: string;
+        recoveryPointAt: string;
+        evidence: Record<string, any>;
+    }>;
+    verify(input: {
+        scenario: DisasterRecoveryDrill['scenario'];
+        drill: DisasterRecoveryDrill;
+        target: string;
+    }): Promise<{
+        healthy: boolean;
+        evidence: Record<string, any>;
+    }>;
+    cleanup(input: {
+        scenario: DisasterRecoveryDrill['scenario'];
+        drill: DisasterRecoveryDrill;
+        target: string;
+    }): Promise<void>;
+}
+export declare class TransportDisasterRecoveryDriver implements DisasterRecoveryDriver {
+    readonly scenario: DisasterRecoveryDrill['scenario'];
+    private transport;
+    constructor(scenario: DisasterRecoveryDrill['scenario'], transport: DisasterRecoveryTransport);
+    restore(input: {
+        drill: DisasterRecoveryDrill;
+        signal: AbortSignal;
+    }): Promise<{
+        target: string;
+        recoveryPointAt: string;
+        evidence: Record<string, any>;
+    }>;
+    verify(input: {
+        drill: DisasterRecoveryDrill;
+        target: string;
+    }): Promise<{
+        healthy: boolean;
+        evidence: Record<string, any>;
+    }>;
+    cleanup(input: {
+        drill: DisasterRecoveryDrill;
+        target: string;
+    }): Promise<void>;
+}

package/dist/maintenance/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './manifest';
+export * from './store';
+export * from './service';
+export * from './queue';
+export * from './drivers';

package/dist/maintenance/maintenance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/maintenance/manifest.d.ts

@@ -0,0 +1,15 @@
+import type { PlatformUpdateDocument } from './types';
+export declare function canonicalJson(value: unknown): string;
+export declare const manifestDigest: (document: PlatformUpdateDocument) => string;
+export declare const documentDigest: (value: unknown) => string;
+export declare const publicKeyFingerprint: (pem: string) => string;
+export declare function verifyUpdateSignature(document: PlatformUpdateDocument, signature: string, publicKeyPem: string): boolean;
+export declare function updateCompatibility(document: PlatformUpdateDocument, input: {
+    schemaVersion: number;
+    currentVersion: string;
+    platform: string;
+    architecture: string;
+}): {
+    compatible: boolean;
+    reasons: string[];
+};

package/dist/maintenance/queue.d.ts

@@ -0,0 +1,9 @@
+import type { QueueOperationHandler } from '../queue';
+import type { CleanupDriver, DisasterRecoveryDriver, PlatformMaintenanceDriver } from './types';
+import { MaintenanceStore } from './store';
+export declare function createMaintenanceQueueHandlers(input: {
+    store: MaintenanceStore;
+    platform?: PlatformMaintenanceDriver;
+    cleanup?: readonly CleanupDriver[];
+    recovery?: readonly DisasterRecoveryDriver[];
+}): Record<string, QueueOperationHandler>;

package/dist/maintenance/service.d.ts

@@ -0,0 +1,31 @@
+import type { ControlPlaneOperation } from '../control-plane';
+import type { CleanupDriver, CleanupPlan, DisasterRecoveryDrill, MaintenanceWindow, UpgradeCampaign } from './types';
+import { DurableOperationQueue } from '../queue';
+import { MaintenanceStore } from './store';
+export declare function maintenanceWindowOpen(window: MaintenanceWindow, now?: Date): boolean;
+export declare class MaintenanceService {
+    readonly store: MaintenanceStore;
+    private now;
+    readonly queue: DurableOperationQueue;
+    constructor(store: MaintenanceStore, queue?: DurableOperationQueue, now?: () => Date);
+    enqueueCampaign(id: string, input?: {
+        approvedBy?: string;
+        overrideWindow?: boolean;
+    }): {
+        campaign: UpgradeCampaign;
+        operation: ControlPlaneOperation;
+    };
+    previewCleanup(input: {
+        projectId: string;
+        kind: CleanupPlan['kind'];
+        criteria: CleanupPlan['criteria'];
+    }, drivers: readonly CleanupDriver[]): Promise<CleanupPlan>;
+    enqueueCleanup(id: string, confirmation: string): {
+        plan: CleanupPlan;
+        operation: ControlPlaneOperation;
+    };
+    enqueueDrill(id: string): {
+        drill: DisasterRecoveryDrill;
+        operation: ControlPlaneOperation;
+    };
+}

package/dist/maintenance/store.d.ts

@@ -0,0 +1,84 @@
+import type { ControlPlaneStore, JsonValue } from '../control-plane';
+import type { CleanupCandidate, CleanupPlan, DisasterRecoveryDrill, MaintenanceWindow, PlatformUpdateDocument, PlatformUpdateManifest, TrustedUpdateKey, UpgradeCampaign, UpgradeTarget } from './types';
+export declare class MaintenanceStore {
+    readonly control: ControlPlaneStore;
+    private now;
+    private id;
+    constructor(control: ControlPlaneStore, now?: () => Date, id?: () => string);
+    addTrustedKey(input: {
+        organizationId: string;
+        name: string;
+        publicKeyPem: string;
+    }): TrustedUpdateKey;
+    key(id: string): TrustedUpdateKey | undefined;
+    revokeKey(id: string): TrustedUpdateKey;
+    importManifest(input: {
+        organizationId: string;
+        keyId: string;
+        document: PlatformUpdateDocument;
+        signature: string;
+        current: {
+            schemaVersion: number;
+            currentVersion: string;
+            platform: string;
+            architecture: string;
+        };
+    }): PlatformUpdateManifest;
+    manifest(id: string): PlatformUpdateManifest | undefined;
+    manifests(organizationId: string): PlatformUpdateManifest[];
+    createWindow(input: {
+        projectId: string;
+        name: string;
+        schedule: string;
+        timezone: string;
+        durationMinutes: number;
+        allowedOperations: string[];
+        requireApproval?: boolean;
+    }): MaintenanceWindow;
+    window(id: string): MaintenanceWindow | undefined;
+    windows(projectId: string): MaintenanceWindow[];
+    createCampaign(input: {
+        projectId: string;
+        manifestId: string;
+        windowId?: string;
+        fromVersion: string;
+        strategy: 'canary' | 'rolling';
+        batchSize: number;
+        healthGate: Record<string, JsonValue>;
+        backupId: string;
+        approvedBy?: string;
+        targets: Array<{
+            serverId?: string;
+            target: string;
+            previousVersion: string;
+        }>;
+    }): UpgradeCampaign;
+    campaign(id: string): UpgradeCampaign | undefined;
+    campaigns(projectId: string): UpgradeCampaign[];
+    targets(id: string): UpgradeTarget[];
+    updateCampaign(id: string, patch: Partial<Pick<UpgradeCampaign, 'status' | 'currentStage'>>): UpgradeCampaign;
+    updateTarget(id: string, patch: Partial<Pick<UpgradeTarget, 'status' | 'evidence' | 'error' | 'startedAt' | 'finishedAt'>>): UpgradeTarget;
+    createCleanup(input: {
+        projectId: string;
+        kind: CleanupPlan['kind'];
+        criteria: CleanupPlan['criteria'];
+        candidates: CleanupCandidate[];
+        ttlMinutes?: number;
+    }): CleanupPlan;
+    cleanup(id: string): CleanupPlan | undefined;
+    cleanups(projectId: string): CleanupPlan[];
+    updateCleanup(id: string, patch: Partial<Pick<CleanupPlan, 'status' | 'confirmation' | 'result'>>): CleanupPlan;
+    createDrill(input: {
+        projectId: string;
+        backupPolicyId?: string;
+        recoveryPointId?: string;
+        topologyId?: string;
+        scenario: DisasterRecoveryDrill['scenario'];
+        isolatedTarget: string;
+        expectedRpoMinutes: number;
+        expectedRtoMinutes: number;
+    }): DisasterRecoveryDrill;
+    drill(id: string): DisasterRecoveryDrill | undefined;
+    drills(projectId: string): DisasterRecoveryDrill[];
+    updateDrill(id: string, patch: Partial<Pick<DisasterRecoveryDrill, 'status' | 'operationId' | 'evidence' | 'measuredRpoMinutes' | 'measuredRtoMinutes' | 'cleanupVerified' | 'error' | 'startedAt' | 'finishedAt'>>): DisasterRecoveryDrill;
+}