@cloudpdf/engine 3.0.0-next.6 → 3.0.0-next.8

package/dist/index.d.cts

@@ -21,6 +21,23 @@ interface HttpClientOptions {
   sessionId?: string;
   /** Replace the global fetch (e.g. in Node tests with undici). */
   fetch?: typeof globalThis.fetch;
+  /**
+   * Document affinity (opt-in; requires a server whose CORS
+   * allowlist includes the header): send `X-CloudPDF-Doc` on
+   * origin-bound doc requests so consistent-hash load balancers pin a
+   * document's traffic to one warm replica. Derived from the request
+   * path (`/v1/docs/:docId/…` — the same extraction the Helm chart's
+   * uri-mode fallback uses); never sent on CDN-rewritten requests.
+   */
+  docAffinityHeader?: boolean;
+  /** Observability: fired once per transport-level retry (engine busy /
+   *  restarting). Lets apps count sheds without wrapping every call. */
+  onRetry?: (info: {
+    path: string;
+    code: string;
+    attempt: number;
+    waitMs: number;
+  }) => void;
 }
 /**
  * Per-document binding for CDN URL rewriting. `CloudDocumentHandle`
@@ -51,6 +68,11 @@ declare class HttpClient {
   private readonly base;
   private readonly tokenFn;
   private readonly fetchFn;
+  private readonly docAffinityHeader;
+  private readonly onRetry;
+  private static readonly MAX_RETRIES;
+  private static readonly RETRY_AFTER_CAP_MS;
+  private static readonly RETRY_AFTER_DEFAULT_MS;
   private readonly sessionId;
   private cdnBinding;
   constructor(opts: HttpClientOptions);
@@ -158,6 +180,7 @@ declare class HttpClient {
   postEmpty(path: string, body: unknown, signal: AbortSignal): Promise<void>;
   private requestJson;
   private request;
+  private execute;
   private parseJsonResponse;
   /**
    * Decide where this request actually goes. With no CDN binding (or

package/dist/index.d.ts

@@ -21,6 +21,23 @@ interface HttpClientOptions {
   sessionId?: string;
   /** Replace the global fetch (e.g. in Node tests with undici). */
   fetch?: typeof globalThis.fetch;
+  /**
+   * Document affinity (opt-in; requires a server whose CORS
+   * allowlist includes the header): send `X-CloudPDF-Doc` on
+   * origin-bound doc requests so consistent-hash load balancers pin a
+   * document's traffic to one warm replica. Derived from the request
+   * path (`/v1/docs/:docId/…` — the same extraction the Helm chart's
+   * uri-mode fallback uses); never sent on CDN-rewritten requests.
+   */
+  docAffinityHeader?: boolean;
+  /** Observability: fired once per transport-level retry (engine busy /
+   *  restarting). Lets apps count sheds without wrapping every call. */
+  onRetry?: (info: {
+    path: string;
+    code: string;
+    attempt: number;
+    waitMs: number;
+  }) => void;
 }
 /**
  * Per-document binding for CDN URL rewriting. `CloudDocumentHandle`
@@ -51,6 +68,11 @@ declare class HttpClient {
   private readonly base;
   private readonly tokenFn;
   private readonly fetchFn;
+  private readonly docAffinityHeader;
+  private readonly onRetry;
+  private static readonly MAX_RETRIES;
+  private static readonly RETRY_AFTER_CAP_MS;
+  private static readonly RETRY_AFTER_DEFAULT_MS;
   private readonly sessionId;
   private cdnBinding;
   constructor(opts: HttpClientOptions);
@@ -158,6 +180,7 @@ declare class HttpClient {
   postEmpty(path: string, body: unknown, signal: AbortSignal): Promise<void>;
   private requestJson;
   private request;
+  private execute;
   private parseJsonResponse;
   /**
    * Decide where this request actually goes. With no CDN binding (or

package/dist/index.js

@@ -809,8 +809,7 @@ var CloudDocumentSecurityService = class {
 	* and `applyCdnAccess` short-circuits to origin; safe to call always.
 	*/
 	async postAccess(signal, body) {
-		const response = await this.http.postJson(wirePaths.access, {
-			docId: this.docId,
+		const response = await this.http.postJson(wirePaths.access(this.docId), {
 			layerName: this.layerName,
 			...body.password ? { password: body.password } : {},
 			mode: body.mode
@@ -1934,7 +1933,7 @@ function fallbackUnknownHead(id) {
 		access: {
 			required: true,
 			reasons: ["permissions-unknown"],
-			endpoint: wirePaths.access
+			endpoint: wirePaths.access(id)
 		}
 	};
 }
@@ -2042,6 +2041,8 @@ var HttpClient = class HttpClient {
 		_defineProperty(this, "base", void 0);
 		_defineProperty(this, "tokenFn", void 0);
 		_defineProperty(this, "fetchFn", void 0);
+		_defineProperty(this, "docAffinityHeader", void 0);
+		_defineProperty(this, "onRetry", void 0);
 		_defineProperty(this, "sessionId", void 0);
 		_defineProperty(this, "cdnBinding", null);
 		this.base = opts.baseUrl.replace(/\/$/, "");
@@ -2049,6 +2050,8 @@ var HttpClient = class HttpClient {
 		this.tokenFn = token === void 0 ? null : typeof token === "function" ? token : () => token;
 		this.sessionId = opts.sessionId ?? null;
 		this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+		this.docAffinityHeader = opts.docAffinityHeader ?? false;
+		this.onRetry = opts.onRetry;
 	}
 	/** Normalized server base URL (no trailing slash). */
 	get baseUrl() {
@@ -2325,7 +2328,7 @@ var HttpClient = class HttpClient {
 		});
 	}
 	async request(path, init) {
-		const { url, extraHeader } = this.resolveOutgoing(path);
+		const { url, extraHeader, routedToCdn } = this.resolveOutgoing(path);
 		const headers = new Headers(init.headers ?? {});
 		if (this.tokenFn) {
 			const token = await this.tokenFn();
@@ -2334,11 +2337,32 @@ var HttpClient = class HttpClient {
 		if (!headers.has("Accept")) headers.set("Accept", "application/json");
 		if (this.sessionId) headers.set("X-Engine-Session-Id", this.sessionId);
 		if (extraHeader) headers.set(extraHeader.name, extraHeader.value);
-		try {
-			return await this.fetchFn(url, {
+		if (this.docAffinityHeader && !routedToCdn) {
+			const doc = /^\/v1\/docs\/([^/]+)\//.exec(path);
+			if (doc) headers.set("X-CloudPDF-Doc", decodeURIComponent(doc[1]));
+		}
+		for (let attempt = 0;; attempt++) {
+			const res = await this.execute(url, {
 				...init,
 				headers
 			});
+			if (res.status !== 503 || attempt >= HttpClient.MAX_RETRIES || isStreamBody(init.body ?? null)) return res;
+			const code = await peekErrorCode(res);
+			if (code === null || !RETRYABLE_503.has(code)) return res;
+			const hinted = Number(res.headers.get("retry-after"));
+			const waitMs = (Number.isFinite(hinted) ? Math.min(Math.max(hinted, 0) * 1e3, HttpClient.RETRY_AFTER_CAP_MS) : HttpClient.RETRY_AFTER_DEFAULT_MS) * (.9 + .2 * Math.random());
+			this.onRetry?.({
+				path,
+				code,
+				attempt,
+				waitMs
+			});
+			await sleepRacingAbort(waitMs, init.signal ?? null);
+		}
+	}
+	async execute(url, init) {
+		try {
+			return await this.fetchFn(url, init);
 		} catch (err) {
 			if (init.signal?.aborted) throw new AbortError$1(init.signal.reason ?? err);
 			if (err?.name === "AbortError") throw new AbortError$1(err.message);
@@ -2364,7 +2388,8 @@ var HttpClient = class HttpClient {
 	resolveOutgoing(path) {
 		if (!this.cdnBinding || !this.cdnBinding.cdn) return {
 			url: `${this.baseUrl}${path}`,
-			extraHeader: null
+			extraHeader: null,
+			routedToCdn: false
 		};
 		const applied = applyCdnAccess({
 			path,
@@ -2375,7 +2400,8 @@ var HttpClient = class HttpClient {
 		});
 		return {
 			url: applied.url,
-			extraHeader: applied.routedToCdn && applied.authHeader ? applied.authHeader : null
+			extraHeader: applied.routedToCdn && applied.authHeader ? applied.authHeader : null,
+			routedToCdn: applied.routedToCdn
 		};
 	}
 	async throwFromBody(res) {
@@ -2395,6 +2421,9 @@ var HttpClient = class HttpClient {
 		throw new EngineError$1(code, `HTTP ${res.status}`, { details: { status: res.status } });
 	}
 };
+_defineProperty(HttpClient, "MAX_RETRIES", 2);
+_defineProperty(HttpClient, "RETRY_AFTER_CAP_MS", 5e3);
+_defineProperty(HttpClient, "RETRY_AFTER_DEFAULT_MS", 1e3);
 function mapStatusToCode(status) {
 	if (status === 401) return EngineErrorCode$1.Unauthenticated;
 	if (status === 403) return EngineErrorCode$1.Forbidden;
@@ -2409,6 +2438,36 @@ function trySerialized(value) {
 	const result = EngineErrorPayloadSchema.safeParse(value);
 	return result.success ? result.data : null;
 }
+const RETRYABLE_503 = /* @__PURE__ */ new Set(["EngineBusy", "EngineRestarting"]);
+function isStreamBody(body) {
+	return typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
+}
+/** Read the error code from a 503 body without consuming the response. */
+async function peekErrorCode(res) {
+	try {
+		const code = (await res.clone().json())?.error?.code;
+		return typeof code === "string" ? code : null;
+	} catch {
+		return null;
+	}
+}
+function sleepRacingAbort(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new AbortError$1(signal.reason ?? "aborted"));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(new AbortError$1(signal?.reason ?? "aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
 //#endregion
 //#region src/CloudEngine.ts
 /**