ব্যর্থতার জন্য ডিজাইন

// --- Errors ---
export class TimeoutError extends Error {
	constructor(ms: number) {
		super(`operation timed out after ${ms}ms`);
		this.name = 'TimeoutError';
	}
}

export class CircuitOpenError extends Error {
	constructor(name: string, retryAfterMs: number) {
		super(`circuit ${name} is open, retry in ${retryAfterMs}ms`);
		this.name = 'CircuitOpenError';
	}
}

export class BulkheadFullError extends Error {
	constructor(name: string) {
		super(`bulkhead ${name} is full`);
		this.name = 'BulkheadFullError';
	}
}

// --- Deadline: a budget that travels with the request ---
export class Deadline {
	private constructor(readonly expiresAt: number) {}

	static in(ms: number): Deadline {
		return new Deadline(Date.now() + ms);
	}

	remainingMs(): number {
		return Math.max(0, this.expiresAt - Date.now());
	}

	expired(): boolean {
		return this.remainingMs() === 0;
	}

	/** Reserve a slice for this hop, leaving the rest for downstream calls. */
	slice(fraction: number): number {
		return Math.floor(this.remainingMs() * fraction);
	}
}

// --- Timeout wrapper that actually cancels the work ---
export async function withTimeout<T>(
	ms: number,
	fn: (signal: AbortSignal) => Promise<T>
): Promise<T> {
	const controller = new AbortController();
	const timer = setTimeout(() => controller.abort(), ms);
	try {
		return await fn(controller.signal);
	} finally {
		clearTimeout(timer);
	}
}

// --- Retry classification ---
export function isRetryable(err: unknown): boolean {
	if (err instanceof TimeoutError) return true;
	if (err instanceof CircuitOpenError) return false; // already shed, do not pile on
	if (err instanceof BulkheadFullError) return false;

	const status = (err as { status?: number }).status;
	if (status === undefined) return true; // network level failure
	if (status === 429 || status === 503 || status === 504) return true;
	return status >= 500 && status < 600;
}

// --- Retry budget: caps retries as a fraction of total traffic ---
export class RetryBudget {
	private attempts = 0;
	private retries = 0;
	private windowStart = Date.now();

	constructor(
		private readonly ratio = 0.1,
		private readonly minRetriesPerSecond = 5,
		private readonly windowMs = 10_000
	) {}

	private roll(): void {
		if (Date.now() - this.windowStart > this.windowMs) {
			this.attempts = 0;
			this.retries = 0;
			this.windowStart = Date.now();
		}
	}

	recordAttempt(): void {
		this.roll();
		this.attempts += 1;
	}

	/**
	 * The budget is what makes retries mathematically safe: no matter how bad
	 * the downstream failure rate gets, retry traffic stays capped at `ratio`
	 * of real traffic, so a struggling service is never tripled.
	 */
	tryConsume(): boolean {
		this.roll();
		const allowance = Math.max(
			this.minRetriesPerSecond * (this.windowMs / 1000),
			this.attempts * this.ratio
		);
		if (this.retries >= allowance) return false;
		this.retries += 1;
		return true;
	}

	get utilisation(): number {
		const allowance = Math.max(
			this.minRetriesPerSecond * (this.windowMs / 1000),
			this.attempts * this.ratio
		);
		return allowance === 0 ? 0 : this.retries / allowance;
	}
}

export interface RetryOptions {
	maxAttempts: number;
	baseDelayMs: number;
	maxDelayMs: number;
	budget?: RetryBudget;
	deadline?: Deadline;
}

/** Full jitter: sleep uniformly between 0 and the exponential cap. */
function fullJitterDelay(attempt: number, baseMs: number, capMs: number): number {
	const exponential = Math.min(capMs, baseMs * 2 ** attempt);
	return Math.floor(Math.random() * exponential);
}

export async function retry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T> {
	let lastError: unknown;

	for (let attempt = 0; attempt < options.maxAttempts; attempt++) {
		options.budget?.recordAttempt();
		try {
			return await fn();
		} catch (err) {
			lastError = err;

			if (!isRetryable(err)) throw err;
			if (attempt === options.maxAttempts - 1) break;
			if (options.budget && !options.budget.tryConsume()) {
				console.log('[retry] budget exhausted, failing fast');
				break;
			}

			const delay = fullJitterDelay(attempt, options.baseDelayMs, options.maxDelayMs);
			if (options.deadline && options.deadline.remainingMs() < delay) {
				console.log('[retry] not enough deadline left to retry');
				break;
			}
			await new Promise((r) => setTimeout(r, delay));
		}
	}
	throw lastError;
}

// --- Circuit breaker ---
type BreakerState = 'closed' | 'open' | 'half-open';

export interface BreakerOptions {
	failureRatioThreshold: number; // e.g. 0.5
	minimumThroughput: number; // do not judge on tiny samples
	windowMs: number;
	cooldownMs: number;
	probeSuccessesToClose: number;
	maxConcurrentProbes: number;
}

export class CircuitBreaker {
	private state: BreakerState = 'closed';
	private successes = 0;
	private failures = 0;
	private windowStart = Date.now();
	private openedAt = 0;
	private probeSuccesses = 0;
	private probesInFlight = 0;

	constructor(
		readonly name: string,
		private readonly options: BreakerOptions
	) {}

	private rollWindow(): void {
		if (Date.now() - this.windowStart > this.options.windowMs) {
			this.successes = 0;
			this.failures = 0;
			this.windowStart = Date.now();
		}
	}

	private trip(): void {
		this.state = 'open';
		this.openedAt = Date.now();
		this.probeSuccesses = 0;
		console.log(`[breaker] ${this.name} -> open`);
	}

	private close(): void {
		this.state = 'closed';
		this.successes = 0;
		this.failures = 0;
		this.windowStart = Date.now();
		console.log(`[breaker] ${this.name} -> closed`);
	}

	private transitionIfCooled(): void {
		if (this.state === 'open' && Date.now() - this.openedAt >= this.options.cooldownMs) {
			this.state = 'half-open';
			this.probeSuccesses = 0;
			this.probesInFlight = 0;
			console.log(`[breaker] ${this.name} -> half-open`);
		}
	}

	async execute<T>(fn: () => Promise<T>): Promise<T> {
		this.rollWindow();
		this.transitionIfCooled();

		if (this.state === 'open') {
			const wait = this.options.cooldownMs - (Date.now() - this.openedAt);
			throw new CircuitOpenError(this.name, Math.max(0, wait));
		}

		// In half-open we let only a few probes through. Flooding a service
		// that just came back is how you knock it over a second time.
		if (this.state === 'half-open') {
			if (this.probesInFlight >= this.options.maxConcurrentProbes) {
				throw new CircuitOpenError(this.name, this.options.cooldownMs);
			}
			this.probesInFlight += 1;
		}

		try {
			const result = await fn();
			this.onSuccess();
			return result;
		} catch (err) {
			this.onFailure();
			throw err;
		} finally {
			if (this.state === 'half-open') this.probesInFlight = Math.max(0, this.probesInFlight - 1);
		}
	}

	private onSuccess(): void {
		if (this.state === 'half-open') {
			this.probeSuccesses += 1;
			if (this.probeSuccesses >= this.options.probeSuccessesToClose) this.close();
			return;
		}
		this.successes += 1;
	}

	private onFailure(): void {
		if (this.state === 'half-open') {
			this.trip();
			return;
		}
		this.failures += 1;

		const total = this.successes + this.failures;
		if (total < this.options.minimumThroughput) return;
		if (this.failures / total >= this.options.failureRatioThreshold) this.trip();
	}

	snapshot(): { state: BreakerState; successes: number; failures: number } {
		return { state: this.state, successes: this.successes, failures: this.failures };
	}
}

// --- Bulkhead: bounded concurrency per dependency ---
export class Bulkhead {
	private inFlight = 0;
	private queue: Array<() => void> = [];

	constructor(
		readonly name: string,
		private readonly maxConcurrent: number,
		private readonly maxQueued: number
	) {}

	async execute<T>(fn: () => Promise<T>): Promise<T> {
		if (this.inFlight >= this.maxConcurrent) {
			if (this.queue.length >= this.maxQueued) {
				throw new BulkheadFullError(this.name);
			}
			await new Promise<void>((resolve) => this.queue.push(resolve));
		}

		this.inFlight += 1;
		try {
			return await fn();
		} finally {
			this.inFlight -= 1;
			const next = this.queue.shift();
			if (next) next();
		}
	}

	snapshot(): { inFlight: number; queued: number } {
		return { inFlight: this.inFlight, queued: this.queue.length };
	}
}

// --- Composing them in the correct order ---
export interface ResilientCallOptions {
	deadline: Deadline;
	perAttemptTimeoutMs: number;
	fallback?: () => Promise<unknown>;
}

/**
 * Order matters and is not arbitrary:
 *   bulkhead  -> caps how much of THIS process a dependency can consume
 *   breaker   -> decides whether to call at all
 *   retry     -> repeats the attempt
 *   timeout   -> bounds a single attempt
 * Putting retry outside the breaker means a tripped circuit fails instantly
 * without burning retry budget, which is exactly what you want.
 */
export function resilientCall<T>(
	bulkhead: Bulkhead,
	breaker: CircuitBreaker,
	budget: RetryBudget,
	work: (signal: AbortSignal) => Promise<T>
) {
	return (options: ResilientCallOptions): Promise<T> =>
		bulkhead.execute(() =>
			retry(
				() =>
					breaker.execute(() =>
						withTimeout(Math.min(options.perAttemptTimeoutMs, options.deadline.remainingMs()), work)
					),
				{
					maxAttempts: 3,
					baseDelayMs: 50,
					maxDelayMs: 2_000,
					budget,
					deadline: options.deadline
				}
			)
		);
}

// --- Demo ---
async function demo(): Promise<void> {
	const bulkhead = new Bulkhead('pricing', 20, 50);
	const breaker = new CircuitBreaker('pricing:quote-fare', {
		failureRatioThreshold: 0.5,
		minimumThroughput: 10,
		windowMs: 10_000,
		cooldownMs: 2_000,
		probeSuccessesToClose: 3,
		maxConcurrentProbes: 2
	});
	const budget = new RetryBudget(0.1, 5, 10_000);

	let healthy = false;
	const quoteFare = resilientCall(bulkhead, breaker, budget, async () => {
		if (!healthy) {
			const err = new Error('pricing unavailable') as Error & { status: number };
			err.status = 503;
			throw err;
		}
		return { fareDirham: 42 };
	});

	for (let i = 0; i < 25; i++) {
		try {
			await quoteFare({ deadline: Deadline.in(2_000), perAttemptTimeoutMs: 300 });
		} catch (err) {
			if (i % 8 === 0) console.log(`request ${i}: ${(err as Error).name}`);
		}
	}
	console.log('breaker after failures:', breaker.snapshot());

	healthy = true;
	await new Promise((r) => setTimeout(r, 2_100)); // wait for cooldown

	for (let i = 0; i < 5; i++) {
		try {
			const fare = await quoteFare({ deadline: Deadline.in(2_000), perAttemptTimeoutMs: 300 });
			console.log('recovered:', fare);
		} catch (err) {
			console.log('probe rejected:', (err as Error).name);
		}
	}
	console.log('breaker after recovery:', breaker.snapshot());
}

void demo();

// --- Request classification ---
export type Priority = 'critical' | 'high' | 'normal' | 'low';

const PRIORITY_ORDER: Priority[] = ['low', 'normal', 'high', 'critical'];

export interface IncomingRequest {
	id: string;
	route: string;
	priority: Priority;
	enqueuedAt: number;
	clientTimeoutMs: number;
	idempotencyKey?: string;
}

export class ShedError extends Error {
	constructor(
		readonly reason: 'queue-full' | 'too-old' | 'priority-shed',
		readonly retryAfterMs: number
	) {
		super(`request shed: ${reason}`);
		this.name = 'ShedError';
	}
}

/**
 * CoDel-inspired admission control. The signal is not queue LENGTH but the
 * time requests spend waiting: a request that has already waited longer than
 * its client will wait is pure waste, and processing it makes things worse.
 */
export class AdmissionController {
	private queue: IncomingRequest[] = [];
	private recentSojournMs: number[] = [];
	private overloadedSince: number | null = null;
	private shedLevel = 0; // index into PRIORITY_ORDER: shed everything below

	constructor(
		private readonly capacity = 200,
		private readonly targetSojournMs = 100,
		private readonly intervalMs = 500
	) {}

	admit(req: IncomingRequest): void {
		if (this.queue.length >= this.capacity) {
			throw new ShedError('queue-full', 1_000);
		}

		const minimumPriority = PRIORITY_ORDER[this.shedLevel];
		if (PRIORITY_ORDER.indexOf(req.priority) < PRIORITY_ORDER.indexOf(minimumPriority)) {
			throw new ShedError('priority-shed', 2_000);
		}

		this.queue.push(req);
	}

	/** Called by workers to pick the next piece of useful work. */
	next(now = Date.now()): IncomingRequest | null {
		while (this.queue.length > 0) {
			const req = this.queue.shift();
			if (!req) return null;

			const waited = now - req.enqueuedAt;
			this.recordSojourn(waited, now);

			// Drop work whose result nobody is waiting for any more.
			if (waited >= req.clientTimeoutMs) {
				console.log(`[shed] dropping ${req.id}, waited ${waited}ms of ${req.clientTimeoutMs}ms`);
				continue;
			}
			return req;
		}
		return null;
	}

	private recordSojourn(waited: number, now: number): void {
		this.recentSojournMs.push(waited);
		if (this.recentSojournMs.length > 200) this.recentSojournMs.shift();

		if (waited > this.targetSojournMs) {
			if (this.overloadedSince === null) this.overloadedSince = now;
			else if (now - this.overloadedSince > this.intervalMs) {
				this.raiseShedLevel();
				this.overloadedSince = now;
			}
		} else {
			this.overloadedSince = null;
			this.lowerShedLevel();
		}
	}

	private raiseShedLevel(): void {
		// Never shed critical traffic: that level is the floor.
		if (this.shedLevel < PRIORITY_ORDER.length - 1) {
			this.shedLevel += 1;
			console.log(`[shed] level up: now rejecting below ${PRIORITY_ORDER[this.shedLevel]}`);
		}
	}

	private lowerShedLevel(): void {
		if (this.shedLevel > 0) {
			this.shedLevel -= 1;
		}
	}

	stats(): { queued: number; shedLevel: Priority; p95SojournMs: number } {
		const sorted = [...this.recentSojournMs].sort((a, b) => a - b);
		const p95 = sorted.length === 0 ? 0 : sorted[Math.floor(sorted.length * 0.95)];
		return {
			queued: this.queue.length,
			shedLevel: PRIORITY_ORDER[this.shedLevel],
			p95SojournMs: p95
		};
	}
}

// --- Idempotency under partial failure ---
type IdempotencyState =
	| { status: 'in-progress'; startedAt: number }
	| { status: 'completed'; response: unknown; completedAt: number };

export class IdempotencyStore {
	private entries = new Map<string, IdempotencyState>();

	constructor(private readonly leaseMs = 30_000) {}

	/**
	 * The three cases that matter:
	 *  - unseen key    -> we claim it and do the work
	 *  - completed key -> replay the stored response, do NOT redo the work
	 *  - in-progress   -> another attempt is running; tell the caller to wait
	 * The third case is the one people forget, and it is exactly what happens
	 * when a client retries after a timeout while the original still runs.
	 */
	async run<T>(key: string, work: () => Promise<T>): Promise<T> {
		const existing = this.entries.get(key);

		if (existing?.status === 'completed') {
			console.log(`[idempotency] replaying stored response for ${key}`);
			return existing.response as T;
		}

		if (existing?.status === 'in-progress') {
			if (Date.now() - existing.startedAt < this.leaseMs) {
				const err = new Error('request already in progress') as Error & { status: number };
				err.status = 409;
				throw err;
			}
			console.log(`[idempotency] lease expired for ${key}, taking over`);
		}

		this.entries.set(key, { status: 'in-progress', startedAt: Date.now() });

		try {
			const result = await work();
			this.entries.set(key, { status: 'completed', response: result, completedAt: Date.now() });
			return result;
		} catch (err) {
			// Failure must release the key, or a transient error would poison
			// this idempotency key forever.
			this.entries.delete(key);
			throw err;
		}
	}

	sweep(retentionMs = 86_400_000): number {
		const cutoff = Date.now() - retentionMs;
		let removed = 0;
		for (const [key, state] of this.entries) {
			if (state.status === 'completed' && state.completedAt < cutoff) {
				this.entries.delete(key);
				removed += 1;
			}
		}
		return removed;
	}
}

// --- Graceful degradation ---
export interface FareQuote {
	fareDirham: number;
	source: 'live-pricing' | 'cached' | 'static-estimate';
	confident: boolean;
}

/**
 * Degradation is a product decision expressed in code: what is the worst
 * answer that is still better than an error page? Ordering the fallbacks
 * explicitly makes that decision visible and reviewable.
 */
export async function quoteFareDegrading(
	livePricing: () => Promise<number>,
	cache: () => Promise<number | null>,
	distanceKm: number
): Promise<FareQuote> {
	try {
		return { fareDirham: await livePricing(), source: 'live-pricing', confident: true };
	} catch {
		const cached = await cache().catch(() => null);
		if (cached !== null) {
			return { fareDirham: cached, source: 'cached', confident: true };
		}
		// Last resort: a formula the client can be told is an estimate.
		return {
			fareDirham: Math.round(12 + distanceKm * 4),
			source: 'static-estimate',
			confident: false
		};
	}
}

// --- Demo ---
async function demo(): Promise<void> {
	const admission = new AdmissionController(200, 100, 200);
	const now = Date.now();

	// A burst: 400 requests arrive, workers can only drain slowly
	let shed = 0;
	for (let i = 0; i < 400; i++) {
		const priority: Priority =
			i % 10 === 0 ? 'critical' : i % 3 === 0 ? 'high' : i % 2 === 0 ? 'normal' : 'low';
		try {
			admission.admit({
				id: `req-${i}`,
				route: '/trips',
				priority,
				enqueuedAt: now - (i < 150 ? 400 : 10), // early ones waited too long
				clientTimeoutMs: 2_000
			});
		} catch {
			shed += 1;
		}
	}
	console.log(`admitted=${400 - shed} shed=${shed}`, admission.stats());

	let processed = 0;
	let dropped = 0;
	for (;;) {
		const req = admission.next(now + 2_500);
		if (!req) break;
		processed += 1;
	}
	dropped = 400 - shed - processed;
	console.log(`processed=${processed} dropped-as-stale=${dropped}`);

	// Idempotency: the same key retried after a timeout
	const store = new IdempotencyStore();
	const charge = () => store.run('trip-9f2c-charge', async () => ({ chargedDirham: 42 }));
	console.log(await charge());
	console.log(await charge()); // replayed, not charged twice

	// Degradation
	console.log(
		await quoteFareDegrading(
			async () => {
				throw new Error('pricing down');
			},
			async () => null,
			7.5
		)
	);
}

void demo();