@getstrata/core 2.2.0 → 2.2.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @getstrata/core changelog
 
+## 2.2.1
+
+F02 — complete queue durability. Queues have leased reservations, recovery and fenced acknowledgement, but still use Redis lists. Persisted retry schedules, execution deadlines, cancellation and the planned Streams migration remain unfinished. Retries currently wait inside the running worker.
+F10 — production public-route tenancy. Separate anonymous access from development tenant headers, support a trusted-host resolver, reject unknown hosts, and accept forwarded hosts only through configured trusted proxies. The shop still lacks the approved-domain mapping.
+F12 — initial administrator provisioning and migration guidance. Automatic demo seeding is fixed. Secure initial-admin provisioning and a consolidated upgrade/operations guide remain.
+Distributed qualification. Cache generations/fill leases, scheduler ownership, OpenTelemetry, body limits and lifecycle controls now exist. Their implementation should no longer be described as entirely pending, but broader failure and capacity qualification is still required.
+
 ## 2.2.0
 
 Consistent model scopes.

package/dist/core/contracts/serviceTokens.d.ts

@@ -1,9 +1,10 @@
 import type { AbilityChecker } from "../auth/abilityChecker";
 import type { ThrottleQuotaPolicy } from "../http/throttleMiddleware";
-import type { TenantResolver } from "../tenant/tenantMiddleware";
+import type { PublicTenancyOptions, TenantResolver } from "../tenant/tenantMiddleware";
 import type { AuthUserDirectory } from "./authUserDirectory";
 import type { ServiceContainerLike } from "./container";
 declare const CORE_THROTTLE_QUOTA_POLICY_TOKEN: import("./container").ServiceToken<ThrottleQuotaPolicy>;
+declare const CORE_PUBLIC_TENANCY_TOKEN: import("./container").ServiceToken<PublicTenancyOptions>;
 declare const CORE_TENANT_RESOLVER_TOKEN: import("./container").ServiceToken<TenantResolver>;
 declare const CORE_HTTP_CLEANUP_TOKEN: import("./container").ServiceToken<(cleanup: () => void) => void>;
 declare const CORE_CONFIG_TOKEN = "core.config";
@@ -19,4 +20,4 @@ declare function isAbilityChecker(value: unknown): value is AbilityChecker;
 declare function isAuthUserDirectory(value: unknown): value is AuthUserDirectory;
 declare function resolveAbilityChecker(container: ServiceContainerLike): AbilityChecker;
 declare function resolveAuthUserDirectory(container: ServiceContainerLike): AuthUserDirectory | null;
-export { CORE_ABILITY_CHECKER_TOKEN, CORE_AUTH_TOKEN, CORE_AUTH_USER_DIRECTORY_TOKEN, CORE_CACHE_TOKEN, CORE_CONFIG_TOKEN, CORE_EVENT_BUS_TOKEN, CORE_HTTP_CLEANUP_TOKEN, CORE_POLICY_GATE_TOKEN, CORE_QUEUE_TOKEN, CORE_TENANT_RESOLVER_TOKEN, CORE_THROTTLE_QUOTA_POLICY_TOKEN, CORE_TOKEN_SERVICE_TOKEN, isAbilityChecker, isAuthUserDirectory, resolveAbilityChecker, resolveAuthUserDirectory, };
+export { CORE_ABILITY_CHECKER_TOKEN, CORE_AUTH_TOKEN, CORE_AUTH_USER_DIRECTORY_TOKEN, CORE_CACHE_TOKEN, CORE_CONFIG_TOKEN, CORE_EVENT_BUS_TOKEN, CORE_HTTP_CLEANUP_TOKEN, CORE_POLICY_GATE_TOKEN, CORE_PUBLIC_TENANCY_TOKEN, CORE_QUEUE_TOKEN, CORE_TENANT_RESOLVER_TOKEN, CORE_THROTTLE_QUOTA_POLICY_TOKEN, CORE_TOKEN_SERVICE_TOKEN, isAbilityChecker, isAuthUserDirectory, resolveAbilityChecker, resolveAuthUserDirectory, };

package/dist/core/http/requestMetaContext.d.ts

@@ -1,5 +1,7 @@
 type RequestMeta = {
     ipAddress: string | null;
+    /** Immediate socket peer recorded by the transport; never a forwarded client header. */
+    peerAddress?: string | null;
     userAgent: string | null;
     request?: Request;
     /** Registered route template; never a URL supplied by the client. */

package/dist/core/queue/createAppQueue.d.ts

@@ -1,5 +1,6 @@
 import type { Queue } from "./index";
 import { createFailedJobService, createQueueWorker, createTrackedJob, type FailedJobService } from "./publicQueue";
+import { resolveQueueConfig } from "./queueConfig";
 declare const FAILED_JOB_SERVICE_TOKEN = "core.failedJobs";
 declare function createAppQueue(driver: "sync" | "async" | "redis", redisUrl?: string, failedJobs?: FailedJobService, registerJobs?: () => void): Queue;
-export { createAppQueue, createFailedJobService, createQueueWorker, createTrackedJob, FAILED_JOB_SERVICE_TOKEN, };
+export { createAppQueue, createFailedJobService, createQueueWorker, createTrackedJob, FAILED_JOB_SERVICE_TOKEN, resolveQueueConfig, };

package/dist/core/queue/failedJobService.d.ts

@@ -5,11 +5,13 @@ declare class FailedJobService {
     constructor(repository: FailedJobRepository);
     recordFailure(input: {
         jobName: string;
+        jobId?: string;
         payload: Record<string, unknown>;
         exception: string;
     }): Promise<FailedJobRecord>;
     listRecent(limit?: number): Promise<FailedJobRecord[]>;
-    retry(id: number): Promise<FailedJobRecord>;
+    /** Admit the replay before deleting its recovery record. Delivery remains at least once. */
+    retry(id: number, enqueue: (record: FailedJobRecord) => Promise<void>): Promise<FailedJobRecord>;
     delete(id: number): Promise<void>;
     flush(): Promise<number>;
 }

package/dist/core/queue/index.d.ts

@@ -1,14 +1,22 @@
 type QueuePriority = "high" | "default" | "low";
+/** Logical identity is stable across automatic recovery and supported manual replay. */
+interface JobContext {
+    readonly jobId: string;
+    readonly signal: AbortSignal;
+    readonly deadlineAtMs?: number;
+}
 declare abstract class Job<TPayload extends object = object> {
     static readonly jobName?: string;
     readonly maxAttempts?: number;
     readonly backoffMs?: number;
     readonly priority?: QueuePriority;
     constructor();
-    abstract handle(payload: TPayload): Promise<void>;
+    abstract handle(payload: TPayload, context?: JobContext): Promise<void>;
 }
 interface Queue {
     close?(): void | Promise<void>;
+    /** Preserve a stored logical identity on deliberate replay; reset execution controls. */
+    replay?<TPayload extends object>(job: Job<TPayload>, payload: TPayload, jobId: string): Promise<void>;
     dispatch<TPayload extends object>(job: Job<TPayload>, payload: TPayload): Promise<void>;
 }
 declare class SyncQueue implements Queue {
@@ -24,5 +32,5 @@ declare class AsyncQueue implements Queue {
     close(): Promise<void>;
 }
 declare function createQueue(driver: "sync" | "async"): Queue;
-export type { Queue, QueuePriority };
+export type { JobContext, Queue, QueuePriority };
 export { AsyncQueue, createQueue, Job, SyncQueue };

package/dist/core/queue/jobRunner.d.ts

@@ -3,9 +3,15 @@ interface QueueJobEnvelope {
     name: string;
     payload: Record<string, unknown>;
     attempts?: number;
+    jobId?: string;
+    deadlineAtMs?: number;
+    cancellable?: boolean;
 }
+declare function parseQueueJobEnvelope(rawPayload: string): QueueJobEnvelope | null;
 declare function runQueueJob(envelope: QueueJobEnvelope, failedJobs: FailedJobService, options?: {
     onFailureRecorded?: () => void;
+    context?: import("./index").JobContext;
+    deferRetry?: (envelope: QueueJobEnvelope, delayMs: number) => Promise<void>;
 }): Promise<void>;
 export type { QueueJobEnvelope };
-export { runQueueJob };
+export { parseQueueJobEnvelope, runQueueJob };

package/dist/core/queue/publicQueue.d.ts

@@ -4,6 +4,7 @@ import type { Job, Queue } from "./index.ts";
 import { jobRegistry } from "./jobRegistry.ts";
 import { runQueueJob } from "./jobRunner.ts";
 import { QueueWorker, RedisQueue } from "./redisQueue.ts";
+import { RedisStreamsWorker } from "./redisStreams";
 import { ResilientQueue } from "./resilientQueue.ts";
 declare function createFailedJobService(): FailedJobService;
 declare function createTrackedJob<TPayload extends object>(name: string, job: Job<TPayload>): Job<TPayload>;
@@ -12,5 +13,5 @@ declare function createProductionQueue(driver: "sync" | "async" | "redis", optio
     failedJobs?: FailedJobService;
     registerJobs?: () => void;
 }): Queue;
-declare function createQueueWorker(redisUrl: string, failedJobs?: FailedJobService): QueueWorker;
+declare function createQueueWorker(redisUrl: string, failedJobs?: FailedJobService): QueueWorker | RedisStreamsWorker;
 export { createFailedJobService, createProductionQueue, createQueueWorker, createTrackedJob, FailedJobRepository, FailedJobService, jobRegistry, QueueWorker, RedisQueue, ResilientQueue, runQueueJob, };

package/dist/core/queue/queueConfig.d.ts

@@ -7,3 +7,6 @@ declare function resolveQueueConfig(): QueueConfig;
 declare const queueConfig: QueueConfig;
 export type { QueueConfig };
 export { queueConfig, resolveQueueConfig };
+declare function resolveRedisQueueTransport(): "lists" | "streams";
+declare function readQueueVisibilityMs(): number;
+export { readQueueVisibilityMs, resolveRedisQueueTransport };

package/dist/core/queue/redisQueue.d.ts

@@ -1,15 +1,11 @@
 import { RedisClient } from "bun";
 import type FailedJobService from "./failedJobService";
-import type { Job, Queue, QueuePriority } from "./index";
-import { type QueueJobEnvelope } from "./jobRunner";
-declare const QUEUE_LIST_KEY: string;
-declare const QUEUE_HIGH_KEY: string;
-declare const QUEUE_LOW_KEY: string;
+import type { Job, Queue } from "./index";
+import { parseQueueJobEnvelope, type QueueJobEnvelope } from "./jobRunner";
+import { QUEUE_HIGH_KEY, QUEUE_LIST_KEY, QUEUE_LOW_KEY, queueKeyForPriority } from "./redisQueueKeys";
 declare function queueProcessingKey(queueKey: string): string;
 declare function queueProcessingLeaseKey(queueKey: string): string;
 declare function reservationExpired(lease: string | null, now: number, visibilityMs: number): boolean;
-declare function queueKeyForPriority(priority?: QueuePriority): string;
-declare function parseQueueJobEnvelope(rawPayload: string): QueueJobEnvelope | null;
 type QueueReservation = {
     id: string;
     owner: string;
@@ -43,5 +39,7 @@ declare class QueueWorker {
     close(): void;
 }
 declare function countPendingQueueJobs(redisUrl: string): Promise<number>;
+export type { StreamReservation, StreamsEnqueueOptions } from "./redisStreams";
+export { migrateLegacyQueueToStreams, RedisStreamsQueue, RedisStreamsWorker, STREAM_GROUP, streamDeadLetterKey, streamQueueKey, updateStreamReservation, } from "./redisStreams";
 export type { QueueJobEnvelope, QueueReservation };
 export { countPendingQueueJobs, parseQueueJobEnvelope, QUEUE_HIGH_KEY, QUEUE_LIST_KEY, QUEUE_LOW_KEY, QueueWorker, queueInvalidKey, queueKeyForPriority, queueProcessingKey, queueProcessingLeaseKey, RedisQueue, reclaimExpiredQueueReservations, reservationExpired, reserveQueueJob, updateQueueReservation, };

package/dist/core/queue/redisQueueKeys.d.ts

@@ -0,0 +1,8 @@
+import type { QueuePriority } from "./index";
+declare const QUEUE_LIST_KEY: string;
+declare const QUEUE_HIGH_KEY: string;
+declare const QUEUE_LOW_KEY: string;
+declare function defaultQueueKeys(): readonly [string, string, string];
+declare const QUEUE_KEYS: readonly [string, string, string];
+declare function queueKeyForPriority(priority?: QueuePriority): string;
+export { defaultQueueKeys, QUEUE_HIGH_KEY, QUEUE_KEYS, QUEUE_LIST_KEY, QUEUE_LOW_KEY, queueKeyForPriority, };

package/dist/core/queue/redisStreams.d.ts

@@ -0,0 +1,73 @@
+import { RedisClient } from "bun";
+import type FailedJobService from "./failedJobService";
+import type { Job, Queue } from "./index";
+import { type QueueJobEnvelope } from "./jobRunner";
+declare const STREAM_GROUP = "strata-workers-v1";
+declare function streamQueueKey(queueKey: string): string;
+declare function streamDeadLetterKey(queueKey: string): string;
+declare function streamRetryKey(queueKey: string): string;
+interface StreamsEnqueueOptions {
+    /** Total lifetime including time waiting and retries, measured from Redis server time. */
+    timeoutMs?: number;
+    cancellable?: boolean;
+}
+declare function streamControlKey(key: string, jobId: string): string;
+declare function cancelStreamJob(client: RedisClient, key: string, jobId: string): Promise<boolean>;
+declare function readStreamCancellation(client: RedisClient, controlKey: string): Promise<boolean>;
+declare function readStreamTime(client: RedisClient): Promise<number>;
+declare function watchStreamDeadline(client: RedisClient, deadlineAtMs: number, remainingMs: number, expire: () => void, fail: (error: unknown) => void): () => void;
+declare function scheduleStreamRetry(client: RedisClient, key: string, reservation: StreamReservation, envelope: QueueJobEnvelope, delayMs: number): Promise<void>;
+declare function promoteStreamRetries(client: RedisClient, key: string): Promise<number>;
+declare function readStreamQueueDepth(client: RedisClient, key: string): Promise<number>;
+type StreamReservation = {
+    id: string;
+    owner: string;
+    payload: string;
+};
+declare function ensureStreamGroup(client: RedisClient, key: string): Promise<void>;
+declare function readStreamEntry(value: unknown, owner: string): StreamReservation | null;
+declare function updateStreamReservation(client: RedisClient, key: string, reservation: StreamReservation, action: "renew" | "ack" | "quarantine", controlKey?: string): Promise<boolean>;
+declare function reserveStreamJob(client: RedisClient, key: string, owner: string, cursor?: string): Promise<{
+    reservation: StreamReservation | null;
+    cursor: string;
+}>;
+declare class RedisStreamsQueue implements Queue {
+    private readonly client;
+    constructor(redisUrl: string);
+    close(): void;
+    dispatch<TPayload extends object>(job: Job<TPayload>, payload: TPayload): Promise<void>;
+    enqueue<TPayload extends object>(job: Job<TPayload>, payload: TPayload, options?: StreamsEnqueueOptions): Promise<string>;
+    replay<TPayload extends object>(job: Job<TPayload>, payload: TPayload, jobId: string): Promise<void>;
+    private admit;
+    cancel(jobId: string): Promise<boolean>;
+}
+declare class RedisStreamsWorker {
+    private readonly failedJobs;
+    private readonly timeoutSeconds;
+    private readonly queueKeys;
+    private readonly client;
+    private readonly owner;
+    private readonly cursors;
+    private processing;
+    private initialized;
+    private running;
+    private stopping;
+    private active?;
+    constructor(redisUrl: string, failedJobs: FailedJobService, timeoutSeconds?: number, queueKeys?: readonly string[]);
+    requestStop(): void;
+    isRunning(): boolean;
+    close(): void;
+    private initialize;
+    private reserve;
+    processNext(): Promise<boolean>;
+    private processOne;
+    private handle;
+    run(): Promise<void>;
+}
+declare function migrateLegacyQueueToStreams(client: RedisClient, options: {
+    maintenance: true;
+    batchSize?: number;
+    queueKeys?: readonly string[];
+}): Promise<number>;
+export type { StreamReservation, StreamsEnqueueOptions };
+export { cancelStreamJob, ensureStreamGroup, migrateLegacyQueueToStreams, promoteStreamRetries, RedisStreamsQueue, RedisStreamsWorker, readStreamCancellation, readStreamEntry, readStreamQueueDepth, readStreamTime, reserveStreamJob, STREAM_GROUP, scheduleStreamRetry, streamControlKey, streamDeadLetterKey, streamQueueKey, streamRetryKey, updateStreamReservation, watchStreamDeadline, };

package/dist/core/queue/types.d.ts

@@ -1,6 +1,7 @@
 interface FailedJobRecord {
     id: number;
     job_name: string;
+    job_id?: string | null;
     payload: Record<string, unknown>;
     exception: string;
     failed_at: Date;

package/dist/core/tenant/publicTenantHost.d.ts

@@ -0,0 +1,11 @@
+interface PublicTenancyOptions {
+    /** Application-owned lookup of approved normalized hostnames; unknown hosts return null. */
+    resolveTenantId(hostname: string): Promise<number | null>;
+    /** Exact immediate socket-peer IP addresses. The proxy must overwrite X-Forwarded-Host. */
+    trustedProxyAddresses?: readonly string[];
+}
+/** Normalize an HTTP authority for approved-domain storage and lookup, without its port. */
+declare function normalizeTenantHostname(authority: string): string;
+declare function createPublicTenantSelector(options: PublicTenancyOptions): (request: Request) => Promise<number>;
+export type { PublicTenancyOptions };
+export { createPublicTenantSelector, normalizeTenantHostname };

package/dist/core/tenant/tenantMiddleware.d.ts

@@ -1,3 +1,4 @@
+import { type PublicTenancyOptions } from "./publicTenantHost";
 import { type TenantContext } from "./tenantContext";
 declare const DEFAULT_TENANT: TenantContext;
 declare function resolveUserTenantId(userId: number): Promise<number>;
@@ -6,7 +7,10 @@ type TenantResolver = (id: number) => Promise<TenantContext | null>;
 interface TenantMiddlewareOptions {
     /** Load trusted application metadata after the framework selects the tenant ID. */
     resolveTenant?: TenantResolver;
+    publicTenancy?: PublicTenancyOptions;
 }
 declare function createTenantMiddleware(options?: TenantMiddlewareOptions): (request: Request, next: () => Promise<Response>) => Promise<Response>;
+export type { PublicTenancyOptions } from "./publicTenantHost";
+export { normalizeTenantHostname } from "./publicTenantHost";
 export type { TenantMiddlewareOptions, TenantResolver };
 export { auditChecksum, createTenantMiddleware, DEFAULT_TENANT, resolveUserTenantId };

package/dist/entries/auth/basicAuthGuard.js

@@ -379,6 +379,7 @@ class ConfigStore {
 
 // ../../src/core/contracts/serviceTokens.ts
 var CORE_THROTTLE_QUOTA_POLICY_TOKEN = createServiceToken("core.throttleQuotaPolicy");
+var CORE_PUBLIC_TENANCY_TOKEN = createServiceToken("core.publicTenancy");
 var CORE_TENANT_RESOLVER_TOKEN = createServiceToken("core.tenantResolver");
 var CORE_HTTP_CLEANUP_TOKEN = createServiceToken("core.httpCleanup");
 var CORE_CONFIG_TOKEN = "core.config";

package/dist/entries/auth/jwtGuard.js

@@ -78,6 +78,7 @@ class ConfigStore {
 
 // ../../src/core/contracts/serviceTokens.ts
 var CORE_THROTTLE_QUOTA_POLICY_TOKEN = createServiceToken("core.throttleQuotaPolicy");
+var CORE_PUBLIC_TENANCY_TOKEN = createServiceToken("core.publicTenancy");
 var CORE_TENANT_RESOLVER_TOKEN = createServiceToken("core.tenantResolver");
 var CORE_HTTP_CLEANUP_TOKEN = createServiceToken("core.httpCleanup");
 var CORE_CONFIG_TOKEN = "core.config";

package/dist/entries/auth/sessionGuard.js

@@ -78,6 +78,7 @@ class ConfigStore {
 
 // ../../src/core/contracts/serviceTokens.ts
 var CORE_THROTTLE_QUOTA_POLICY_TOKEN = createServiceToken("core.throttleQuotaPolicy");
+var CORE_PUBLIC_TENANCY_TOKEN = createServiceToken("core.publicTenancy");
 var CORE_TENANT_RESOLVER_TOKEN = createServiceToken("core.tenantResolver");
 var CORE_HTTP_CLEANUP_TOKEN = createServiceToken("core.httpCleanup");
 var CORE_CONFIG_TOKEN = "core.config";

package/dist/entries/contracts/serviceTokens.js

@@ -78,6 +78,7 @@ class ConfigStore {
 
 // ../../src/core/contracts/serviceTokens.ts
 var CORE_THROTTLE_QUOTA_POLICY_TOKEN = createServiceToken("core.throttleQuotaPolicy");
+var CORE_PUBLIC_TENANCY_TOKEN = createServiceToken("core.publicTenancy");
 var CORE_TENANT_RESOLVER_TOKEN = createServiceToken("core.tenantResolver");
 var CORE_HTTP_CLEANUP_TOKEN = createServiceToken("core.httpCleanup");
 var CORE_CONFIG_TOKEN = "core.config";
@@ -132,6 +133,7 @@ export {
   CORE_EVENT_BUS_TOKEN,
   CORE_HTTP_CLEANUP_TOKEN,
   CORE_POLICY_GATE_TOKEN,
+  CORE_PUBLIC_TENANCY_TOKEN,
   CORE_QUEUE_TOKEN,
   CORE_TENANT_RESOLVER_TOKEN,
   CORE_THROTTLE_QUOTA_POLICY_TOKEN,