@stacksjs/ts-cloud 0.7.56 → 0.7.57

package/dist/backups/model.d.ts

@@ -0,0 +1,121 @@
+import type { JsonValue } from '../control-plane';
+export type BackupDestinationProvider = 'aws_s3' | 's3_compatible' | 'aws_backup';
+export type BackupResourceKind = 'managed_database' | 'logical_database' | 'volume' | 'files' | 'control_plane' | 'infrastructure';
+export interface BackupDestination {
+    id: string;
+    organizationId: string;
+    projectId: string;
+    name: string;
+    provider: BackupDestinationProvider;
+    endpoint?: string;
+    endpointPolicy: 'public_https' | 'allow_private';
+    bucket?: string;
+    prefix: string;
+    region?: string;
+    forcePathStyle: boolean;
+    credentialRef?: string;
+    encryption: 'provider' | 'client_side' | 'both';
+    encryptionKeyRef?: string;
+    immutability: {
+        objectLock?: boolean;
+        defaultRetentionDays?: number;
+    };
+    status: 'untested' | 'healthy' | 'failing' | 'disabled';
+    lastTestedAt?: string;
+    lastSuccessAt?: string;
+    lastFailureAt?: string;
+    lastError?: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface BackupRetention {
+    keepLast?: number;
+    hourly?: number;
+    daily?: number;
+    weekly?: number;
+    monthly?: number;
+    expireAfterDays?: number;
+}
+export interface BackupPolicy {
+    id: string;
+    organizationId: string;
+    projectId: string;
+    environmentId?: string;
+    resourceId?: string;
+    dataServiceId?: string;
+    destinationId: string;
+    name: string;
+    resourceKind: BackupResourceKind;
+    schedule: string;
+    timezone: string;
+    retention: BackupRetention;
+    compression: 'none' | 'gzip' | 'zstd';
+    encryption: 'destination' | 'client_side' | 'both';
+    includePatterns: string[];
+    excludePatterns: string[];
+    expectedRpoMinutes: number;
+    expectedRtoMinutes: number;
+    healthCheckId?: string;
+    enabled: boolean;
+    nextRunAt?: string;
+    lastRunAt?: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface RecoveryPoint {
+    id: string;
+    projectId: string;
+    policyId?: string;
+    destinationId: string;
+    resourceId?: string;
+    dataServiceId?: string;
+    backupJobId?: string;
+    kind: BackupResourceKind;
+    pointInTime: string;
+    uri: string;
+    sizeBytes: number;
+    checksum: string;
+    manifest: Record<string, JsonValue>;
+    toolVersion?: string;
+    engineVersion?: string;
+    expiresAt?: string;
+    lockedUntil?: string;
+    held: boolean;
+    pinned: boolean;
+    status: 'pending' | 'available' | 'failed' | 'deleting' | 'deleted';
+    verificationState: 'unverified' | 'verifying' | 'verified' | 'corrupt' | 'failed';
+    verifiedAt?: string;
+    durationMs?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface BackupJob {
+    id: string;
+    projectId: string;
+    policyId?: string;
+    recoveryPointId?: string;
+    operationId?: string;
+    kind: 'backup' | 'restore' | 'verify' | 'drill' | 'cleanup';
+    status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'cleanup_required';
+    idempotencyKey: string;
+    target: Record<string, JsonValue>;
+    restoreMode?: 'isolated' | 'in_place';
+    cancellability: 'safe' | 'checkpoint_only' | 'provider_uncancellable';
+    safetyBackupId?: string;
+    healthResult?: Record<string, JsonValue>;
+    progress: Record<string, JsonValue>;
+    error?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface BackupCoverage {
+    policy: BackupPolicy;
+    lastRecoveryPoint?: RecoveryPoint;
+    missedRpo: boolean;
+    unverified: number;
+    destinationHealthy: boolean;
+}

package/dist/backups/s3-destination.d.ts

@@ -0,0 +1,85 @@
+import type { BackupDestination } from './model';
+export interface BackupSecretBackend {
+    resolve(reference: string): Promise<string>;
+}
+export interface BackupObjectClient {
+    putObject(input: {
+        bucket: string;
+        key: string;
+        body: string | Buffer | Uint8Array;
+        contentType?: string;
+        metadata?: Record<string, string>;
+    }): Promise<void>;
+    getObjectBytes(bucket: string, key: string): Promise<{
+        body: Uint8Array;
+        contentLength?: number;
+    }>;
+    deleteObject(bucket: string, key: string): Promise<void>;
+    createMultipartUpload(bucket: string, key: string, options?: {
+        contentType?: string;
+        metadata?: Record<string, string>;
+    }): Promise<{
+        UploadId: string;
+    }>;
+    uploadPart(bucket: string, key: string, uploadId: string, partNumber: number, body: Uint8Array | Buffer): Promise<{
+        ETag: string;
+    }>;
+    completeMultipartUpload(bucket: string, key: string, uploadId: string, parts: Array<{
+        PartNumber: number;
+        ETag: string;
+    }>): Promise<void>;
+    abortMultipartUpload(bucket: string, key: string, uploadId: string): Promise<void>;
+}
+export interface MultipartCheckpoint {
+    uploadId: string;
+    key: string;
+    parts: Array<{
+        PartNumber: number;
+        ETag: string;
+    }>;
+    bytesUploaded: number;
+    encryptionIv?: string;
+    plaintextChecksum?: string;
+}
+export interface StoredBackup {
+    uri: string;
+    key: string;
+    sizeBytes: number;
+    checksum: string;
+    manifest: {
+        format: 'ts-cloud-backup-v1';
+        encrypted: boolean;
+        plaintextChecksum: string;
+        storageChecksum: string;
+        contentType: string;
+    };
+}
+export declare function encryptBackup(value: Uint8Array, secret: string, suppliedIv?: Uint8Array): Buffer;
+export declare function decryptBackup(value: Uint8Array, secret: string): Buffer;
+export declare function backupCredentialStatus(_destination: BackupDestination, secrets: BackupSecretBackend, now?: Date): Promise<{
+    status: 'default' | 'static' | 'valid' | 'expiring' | 'expired' | 'invalid';
+    expiresAt?: string;
+}>;
+export declare class S3BackupDestinationAdapter {
+    private readonly secrets;
+    private readonly clientFactory;
+    private readonly multipartThreshold;
+    private readonly partSize;
+    constructor(secrets: BackupSecretBackend, clientFactory?: (destination: BackupDestination, credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    }) => BackupObjectClient, multipartThreshold?: number, partSize?: number);
+    private client;
+    test(destination: BackupDestination): Promise<void>;
+    upload(destination: BackupDestination, input: {
+        key: string;
+        body: Uint8Array;
+        contentType?: string;
+        resume?: MultipartCheckpoint;
+        checkpoint?: (value: MultipartCheckpoint) => void;
+    }): Promise<StoredBackup>;
+    download(destination: BackupDestination, stored: Pick<StoredBackup, 'key' | 'checksum' | 'manifest'>): Promise<Buffer>;
+    abortPartial(destination: BackupDestination, checkpoint: MultipartCheckpoint): Promise<void>;
+    delete(destination: BackupDestination, key: string): Promise<void>;
+}

package/dist/backups/s3-destination.test.d.ts

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

package/dist/backups/service.d.ts

@@ -0,0 +1,80 @@
+import type { JsonValue } from '../control-plane';
+import type { QueueExecutionContext, QueueOperationHandler } from '../queue';
+import type { BackupDestination, BackupJob, BackupPolicy, RecoveryPoint } from './model';
+import type { MultipartCheckpoint, StoredBackup } from './s3-destination';
+import { DurableOperationQueue } from '../queue';
+import { BackupStore } from './store';
+export type BackupSourceResult = {
+    mode: 'object';
+    key: string;
+    body: Uint8Array;
+    contentType?: string;
+    manifest: Record<string, JsonValue>;
+    toolVersion?: string;
+    engineVersion?: string;
+} | {
+    mode: 'external';
+    uri: string;
+    checksum: string;
+    sizeBytes: number;
+    manifest: Record<string, JsonValue>;
+    toolVersion?: string;
+    engineVersion?: string;
+};
+export interface BackupSourceAdapter {
+    create(policy: BackupPolicy, context: QueueExecutionContext): Promise<BackupSourceResult>;
+    verifyExternal?(point: RecoveryPoint, context: QueueExecutionContext): Promise<Record<string, JsonValue>>;
+    verify?(point: RecoveryPoint, body: Uint8Array, context: QueueExecutionContext): Promise<Record<string, JsonValue>>;
+    restore(point: RecoveryPoint, body: Uint8Array | undefined, target: Record<string, JsonValue>, context: QueueExecutionContext): Promise<Record<string, JsonValue>>;
+    validateHealth?(target: Record<string, JsonValue>, context: QueueExecutionContext): Promise<Record<string, JsonValue>>;
+    cleanup?(target: Record<string, JsonValue>, context: QueueExecutionContext): Promise<void>;
+    deleteExternal?(point: RecoveryPoint, context: QueueExecutionContext): Promise<void>;
+}
+export interface BackupDestinationAdapter {
+    upload(destination: BackupDestination, input: {
+        key: string;
+        body: Uint8Array;
+        contentType?: string;
+        resume?: MultipartCheckpoint;
+        checkpoint?: (value: MultipartCheckpoint) => void;
+    }): Promise<StoredBackup>;
+    download(destination: BackupDestination, stored: Pick<StoredBackup, 'key' | 'checksum' | 'manifest'>): Promise<Buffer>;
+    delete(destination: BackupDestination, key: string): Promise<void>;
+    abortPartial?(destination: BackupDestination, checkpoint: MultipartCheckpoint): Promise<void>;
+}
+export declare class BackupCoordinator {
+    readonly store: BackupStore;
+    readonly queue: DurableOperationQueue;
+    private readonly now;
+    constructor(store: BackupStore, queue: DurableOperationQueue, now?: () => Date);
+    enqueueBackup(policy: BackupPolicy, scheduledFor?: string, actorId?: string): BackupJob;
+    enqueueDue(at?: Date): BackupJob[];
+    enqueueVerification(point: RecoveryPoint): BackupJob;
+    planRestore(point: RecoveryPoint, input: {
+        mode: 'isolated' | 'in_place';
+        target: Record<string, JsonValue>;
+        targetName: string;
+        confirm?: string;
+        recentAuth?: boolean;
+        downtimeAcknowledged?: boolean;
+        safetyBackupId?: string;
+    }): {
+        point: RecoveryPoint;
+        mode: 'isolated' | 'in_place';
+        target: Record<string, JsonValue>;
+        warnings: string[];
+    };
+    enqueueRestore(point: RecoveryPoint, input: Parameters<BackupCoordinator['planRestore']>[1] & {
+        drill?: boolean;
+        actorId?: string;
+    }): BackupJob;
+    enqueueRetention(at?: Date): BackupJob[];
+}
+export declare function createBackupQueueHandlers(input: {
+    store: BackupStore;
+    queue: DurableOperationQueue;
+    resolveSource: (policy: BackupPolicy) => BackupSourceAdapter | undefined;
+    resolveDestination: (destination: BackupDestination) => BackupDestinationAdapter | undefined;
+    validateHealth?: (policy: BackupPolicy, target: Record<string, JsonValue>) => Promise<Record<string, JsonValue>>;
+    now?: () => Date;
+}): Record<string, QueueOperationHandler>;

package/dist/backups/service.test.d.ts

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

package/dist/backups/store.d.ts

@@ -0,0 +1,30 @@
+import type { ControlPlaneStore } from '../control-plane';
+import type { BackupCoverage, BackupDestination, BackupJob, BackupPolicy, RecoveryPoint } from './model';
+export declare function validateBackupDestination(input: Omit<BackupDestination, 'id' | 'version' | 'createdAt' | 'updatedAt'>): void;
+export declare class BackupStore {
+    readonly controlPlane: ControlPlaneStore;
+    private readonly now;
+    constructor(controlPlane: ControlPlaneStore, now?: () => Date);
+    createDestination(input: Omit<BackupDestination, 'id' | 'version' | 'createdAt' | 'updatedAt'>): BackupDestination;
+    getDestination(id: string): BackupDestination | undefined;
+    listDestinations(projectId: string): BackupDestination[];
+    recordDestinationTest(id: string, result: {
+        ok: boolean;
+        error?: string;
+    }): BackupDestination;
+    createPolicy(input: Omit<BackupPolicy, 'id' | 'version' | 'createdAt' | 'updatedAt' | 'nextRunAt'>): BackupPolicy;
+    getPolicy(id: string): BackupPolicy | undefined;
+    listPolicies(projectId: string, environmentId?: string): BackupPolicy[];
+    duePolicies(at?: Date): BackupPolicy[];
+    advancePolicy(id: string, scheduledFor: string): BackupPolicy;
+    createJob(input: Omit<BackupJob, 'id' | 'createdAt' | 'updatedAt'>): BackupJob;
+    getJob(id: string): BackupJob | undefined;
+    listJobs(projectId: string): BackupJob[];
+    updateJob(id: string, patch: Partial<Pick<BackupJob, 'status' | 'operationId' | 'recoveryPointId' | 'progress' | 'healthResult' | 'error' | 'startedAt' | 'finishedAt' | 'safetyBackupId'>>): BackupJob;
+    createRecoveryPoint(input: Omit<RecoveryPoint, 'id' | 'createdAt' | 'updatedAt'>): RecoveryPoint;
+    getRecoveryPoint(id: string): RecoveryPoint | undefined;
+    listRecoveryPoints(projectId: string, policyId?: string): RecoveryPoint[];
+    updateRecoveryPoint(id: string, patch: Partial<Pick<RecoveryPoint, 'status' | 'verificationState' | 'verifiedAt' | 'held' | 'pinned' | 'manifest' | 'durationMs'>>): RecoveryPoint;
+    retentionCandidates(at?: Date): RecoveryPoint[];
+    coverage(projectId: string, at?: Date): BackupCoverage[];
+}

package/dist/backups/store.test.d.ts

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