@nebius/js-sdk 0.1.0

package/dist/cjs/runtime/request.js

@@ -0,0 +1,635 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Request = exports.DefaultRetriableCodes = void 0;
+const grpc_js_1 = require("@grpc/grpc-js");
+const deadline_1 = require("@grpc/grpc-js/build/src/deadline");
+const index_1 = require("../api/google/rpc/index");
+const index_2 = require("../api/nebius/common/v1/index");
+const error_1 = require("./error");
+const resetmask_1 = require("./resetmask");
+const cancelable_1 = require("./util/cancelable");
+const logging_1 = require("./util/logging");
+exports.DefaultRetriableCodes = [
+    index_1.Code.RESOURCE_EXHAUSTED,
+    index_1.Code.UNAVAILABLE,
+];
+const RESET_MASK_HEADER = 'x-resetmask';
+const IDEMPOTENCY_HEADER = 'x-idempotency-key';
+function shouldUseIdempotencyKey(methodName) {
+    if (!methodName)
+        return false;
+    const m = methodName.toLowerCase();
+    // Non-mutating methods that should NOT add idempotency keys
+    if (m === 'get' || m === 'getbyname' || m === 'list' || m === 'listoperationsbyparent') {
+        return false;
+    }
+    // For all other unary methods, add it (Create/Update/Delete/Start/Stop/etc.)
+    return true;
+}
+function generateIdempotencyKey() {
+    try {
+        // Prefer crypto.randomUUID if available (RFC 4122 v4)
+        const crypto = require('crypto');
+        if (typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+        // Fallback to randomBytes and format as UUID v4
+        const bytes = crypto.randomBytes(16);
+        // Set version (4) and variant (10xx)
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = bytes.toString('hex');
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+    catch {
+        // Last-resort non-crypto fallback with correct UUIDv4 shape
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+            const r = (Math.random() * 16) | 0;
+            const v = c === 'x' ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+}
+const DEFAULT_OVERALL_TIMEOUT = 15 * 60000; // 15 minutes
+const DEFAULT_REQUEST_TIMEOUT = 60000; // 1 minute
+const DEFAULT_RETRY_COUNT = 3;
+const DEFAULT_PER_RETRY_TIMEOUT = DEFAULT_REQUEST_TIMEOUT / DEFAULT_RETRY_COUNT;
+class CancelledError extends error_1.NebiusGrpcError {
+    constructor(reason) {
+        const message = reason
+            ? `Request cancelled on client: ${reason}`
+            : 'Request cancelled on client';
+        const st = index_1.Status.create({
+            code: index_1.Code.CANCELLED.code,
+            message,
+            details: [],
+        });
+        const err = Object.assign(new Error(message), {
+            code: index_1.Code.CANCELLED.code,
+            details: message,
+            metadata: new grpc_js_1.Metadata(),
+        });
+        super(err, st);
+    }
+}
+class Request {
+    sdk;
+    serviceName;
+    methodName;
+    addr;
+    serializer;
+    deserializer;
+    request;
+    requestMetadata;
+    requestOptions;
+    $type = 'nebius.sdk.Request';
+    // Promises
+    result;
+    initialMetadata;
+    trailingMetadata;
+    status;
+    requestId;
+    traceId;
+    _resolveInitialMd;
+    _resolveTrailingMd;
+    _resolveStatus;
+    _resolveReqId;
+    _resolveTraceId;
+    logger;
+    _maybeReqId;
+    _maybeTraceId;
+    _maybeStatus;
+    // Cancellation and cleanup helpers
+    _canceled = false;
+    _calls = new Set();
+    constructor(sdk, serviceName, methodName, addr, serializer, deserializer, request, requestMetadata, requestOptions) {
+        this.sdk = sdk;
+        this.serviceName = serviceName;
+        this.methodName = methodName;
+        this.addr = addr;
+        this.serializer = serializer;
+        this.deserializer = deserializer;
+        this.request = request;
+        this.requestMetadata = requestMetadata;
+        this.requestOptions = requestOptions;
+        const path = `/${this.serviceName}/${this.methodName}`;
+        const client = this.sdk.getClientByAddress(this.addr);
+        const metadata = this.requestMetadata ?? new grpc_js_1.Metadata();
+        this.logger = this.sdk.logger.child('request', {
+            service: this.serviceName,
+            method: this.methodName,
+            address: this.addr,
+            started_at: new Date().toISOString(),
+        });
+        this.logger.trace('Request initialized');
+        const baseOptions = this.requestOptions
+            ? { ...this.requestOptions }
+            : undefined;
+        if (baseOptions?.deadline !== undefined && typeof baseOptions.deadline === 'number') {
+            baseOptions.deadline = new Date(baseOptions.deadline);
+        }
+        this.initialMetadata = new Promise((res) => (this._resolveInitialMd = res));
+        this.trailingMetadata = new Promise((res) => (this._resolveTrailingMd = res));
+        this.status = new Promise((res) => (this._resolveStatus = res));
+        this.requestId = new Promise((res) => (this._resolveReqId = res));
+        this.traceId = new Promise((res) => (this._resolveTraceId = res));
+        this.status = this.status.then((st) => {
+            this._maybeStatus = st || this._maybeStatus;
+            if (st) {
+                this.logger = this.logger.withFields({
+                    status: this._maybeStatus,
+                });
+                this.logger.debug('Request status resolved');
+            }
+            return st;
+        });
+        const maxRetries = Math.max(0, baseOptions?.RetryCount ?? DEFAULT_RETRY_COUNT);
+        this.logger = this.logger.withFields({ max_retries: maxRetries });
+        // Generate idempotency key once per logical request and reuse across retries
+        const useIdemp = shouldUseIdempotencyKey(methodName);
+        const idempotencyKey = useIdemp ? generateIdempotencyKey() : undefined;
+        if (useIdemp) {
+            this.logger = this.logger.withFields({ idempotency_key: idempotencyKey });
+            this.logger.trace('Using idempotency key for this request');
+        }
+        let overallMs = DEFAULT_OVERALL_TIMEOUT;
+        if (baseOptions?.deadline !== undefined) {
+            overallMs = (0, deadline_1.getRelativeTimeout)(baseOptions.deadline);
+            this.logger.trace('Using caller-provided overall deadline', { overall_ms: overallMs });
+        }
+        else {
+            this.logger.trace('Using default overall deadline', { overall_ms: overallMs });
+        }
+        let requestTimeout = DEFAULT_REQUEST_TIMEOUT;
+        if (baseOptions?.RequestTimeout !== undefined) {
+            requestTimeout = baseOptions.RequestTimeout;
+            this.logger.trace('Using caller-provided request timeout', {
+                request_timeout_ms: requestTimeout,
+            });
+        }
+        else {
+            this.logger.trace('Using default request timeout', { request_timeout_ms: requestTimeout });
+        }
+        let perRetry = DEFAULT_PER_RETRY_TIMEOUT;
+        if (baseOptions?.PerRetryTimeout !== undefined) {
+            perRetry = baseOptions.PerRetryTimeout;
+            this.logger.trace('Using caller-provided per-retry timeout', { per_retry_ms: perRetry });
+        }
+        else {
+            this.logger.trace('Using default per-retry timeout', { per_retry_ms: perRetry });
+        }
+        const overallDeadline = new Date(Date.now() + overallMs);
+        this.logger = this.logger.withFields({
+            overall_timeout_ms: overallMs,
+            per_retry_timeout_ms: perRetry,
+            overall_deadline: overallDeadline,
+        });
+        // Possibly inject parentId into request
+        injectParentIdIfNeeded(methodName, sdk?.parentId(), this.request, this.logger);
+        // Ensure reset mask header for update methods if absent
+        const isUpdate = (methodName || '').toLowerCase() === 'update';
+        if (isUpdate) {
+            this.logger.trace('Detected update method, inserting reset mask if needed');
+            const existing = metadata.get(RESET_MASK_HEADER);
+            if (!existing || existing.length === 0) {
+                const rm = (0, resetmask_1.resetMaskFromMessage)(this.request);
+                if (rm) {
+                    metadata.set(RESET_MASK_HEADER, rm.marshal());
+                    this.logger.trace('Inserted reset mask into metadata', { reset_mask: rm });
+                }
+            }
+        }
+        // Ensure idempotency key header (same across retries)
+        if (useIdemp && idempotencyKey) {
+            const existing = metadata.get(IDEMPOTENCY_HEADER);
+            if (!existing || existing.length === 0) {
+                metadata.set(IDEMPOTENCY_HEADER, idempotencyKey);
+                this.logger.trace('Inserted idempotency key into metadata');
+            }
+            else {
+                this.logger = this.logger.withFields({ idempotency_key: existing });
+                this.logger.trace('Idempotency key already set in metadata');
+            }
+        }
+        // Start the request flow with authorization outer-loop and internal retry attempts
+        this.result = new Promise((resolve, reject) => {
+            // Helper: compute ms left until a deadline
+            const timeLeftMs = (deadline) => {
+                if (!deadline)
+                    return undefined;
+                const now = Date.now();
+                if (deadline instanceof Date)
+                    return Math.max(0, deadline.getTime() - now);
+                if (typeof deadline === 'number')
+                    return Math.max(0, deadline - now);
+                return undefined;
+            };
+            // Inner: run one authorized request window that includes several retries using the same authorized metadata
+            const runAttempt = (attempt, callMd, attemptDeadline) => {
+                if (this._canceled) {
+                    this.logger.debug('Request canceled by client before attempt start', { attempt });
+                    const err = new CancelledError();
+                    this._resolveStatus(err.status);
+                    reject(err);
+                    return;
+                }
+                let logger = this.logger.withFields({ attempt });
+                logger.trace('Starting request attempt');
+                // Compute a per-retry deadline relative to now, but clip it to the
+                // authorized request attempt deadline if it is earlier.
+                let perDeadline = new Date(Date.now() + perRetry);
+                if (perDeadline.getTime() > attemptDeadline.getTime()) {
+                    perDeadline = attemptDeadline;
+                }
+                const deadlineOpt = {
+                    ...(baseOptions ?? {}),
+                    deadline: perDeadline,
+                };
+                logger = logger.withFields({
+                    per_retry_deadline: perDeadline,
+                    maxRetries,
+                    perRetryMs: perRetry,
+                });
+                logger.debug('Request attempt starting');
+                const call = client.makeUnaryRequest(path, this.serializer, this.deserializer, this.request, callMd, deadlineOpt, (err, resp) => {
+                    try {
+                        this._calls.delete(call);
+                        call.removeAllListeners();
+                    }
+                    catch (err) {
+                        logger.warn('Error during call cleanup', { err });
+                    }
+                    logger.trace('Request attempt removed from active set', {
+                        active_calls: this._calls.size,
+                    });
+                    if (err) {
+                        logger.trace('Request attempt returned error', { err });
+                        call.cancel(); // ensure call is fully closed
+                        const wrapped = err;
+                        // Metadata-derived requestId/traceId if any
+                        if (wrapped?.metadata) {
+                            const md = wrapped.metadata;
+                            this._safeResolveIdsFromMd(md);
+                        }
+                        // Determine retriable
+                        const retriable = this._isRetriableError(wrapped);
+                        const errLogger = logger.withFields({ err: wrapped, is_retriable: retriable });
+                        errLogger.error('Request attempt failed');
+                        if (retriable && attempt < maxRetries && !this._canceled) {
+                            errLogger.trace('Retrying request attempt after retriable error');
+                            runAttempt(attempt + 1, callMd, attemptDeadline);
+                            return;
+                        }
+                        if (retriable) {
+                            errLogger.error('Request retries exhausted, final failure');
+                        }
+                        else if (this._canceled) {
+                            errLogger.warn('Request was canceled, rejecting');
+                        }
+                        else {
+                            errLogger.error('Request failed (non-retriable)');
+                        }
+                        errLogger.trace('Final request error, rejecting');
+                        // Resolve status even on error
+                        const st = decodeStatusFromError(err) ??
+                            index_1.Status.create({
+                                code: err.code,
+                                message: err.message,
+                                details: [],
+                            });
+                        this._resolveStatus(st);
+                        reject(wrapped);
+                        return;
+                    }
+                    else if (!resp) {
+                        logger.trace('Request attempt returned neither error nor response, failing');
+                        // Handle missing response
+                        const st = index_1.Status.create({
+                            code: index_1.Code.UNKNOWN.code,
+                            message: 'Neither response, nor error received from server',
+                            details: [],
+                        });
+                        this._resolveStatus(st);
+                        reject(Error('Neither response, nor error received from server'));
+                        return;
+                    }
+                    logger.debug('Request attempt succeeded');
+                    resolve(resp);
+                });
+                logger.trace('Request attempt sent, attaching listeners');
+                // Attach event listeners for metadata and status
+                call.on('metadata', (md2) => {
+                    logger.trace('Received initial metadata');
+                    this._resolveInitialMd(md2);
+                    this._safeResolveIdsFromMd(md2);
+                });
+                call.on('status', (s) => {
+                    logger.trace('Received status event', { status: s });
+                    const st = decodeStatusFromStatusEvent(s);
+                    this._resolveStatus(st);
+                    const md = s?.metadata;
+                    if (md)
+                        this._safeResolveIdsFromMd(md);
+                    if (s?.metadata)
+                        this._resolveTrailingMd(s.metadata);
+                });
+                // track active call for possible cancellation/cleanup
+                this._calls.add(call);
+                this.logger.trace('Tracking call for potential cancellation', { calls: this._calls.size });
+            };
+            // Outer: authorization loop
+            const startAuthorizedFlow = async () => {
+                // Compute overall deadline (already prepared above)
+                // Prepare baseline metadata (already has reset-mask and idempotency if needed)
+                const baseMd = metadata;
+                const disableAuth = baseOptions?.authorizationDisable === true;
+                const authOptions = baseOptions?.authorizationOptions;
+                const provider = this.sdk.getAuthorizationProvider();
+                if (disableAuth || !provider) {
+                    this.logger.trace(disableAuth
+                        ? 'Authorization disabled by call options; starting request attempts without auth.'
+                        : 'No authorization provider; starting request attempts without auth.');
+                    // Single authorized window: requestTimeout, clipped by overall deadline
+                    const attemptDeadline = new Date(Math.min(Date.now() + requestTimeout, overallDeadline.getTime()));
+                    runAttempt(0, baseMd, attemptDeadline);
+                    return;
+                }
+                const auth = provider.authenticator();
+                let authAttempt = 0;
+                while (true) {
+                    if (this._canceled) {
+                        const cerr = new CancelledError('cancelled before authentication');
+                        this._resolveStatus(cerr.status);
+                        reject(cerr);
+                        return;
+                    }
+                    authAttempt += 1;
+                    const left = timeLeftMs(overallDeadline);
+                    const timeoutMs = left === undefined ? undefined : Math.max(0, left);
+                    const aLog = this.logger.withFields({ auth_attempt: authAttempt, left, timeoutMs });
+                    aLog.debug('Starting authentication attempt');
+                    // Always start from the baseline metadata to avoid stacking headers between attempts
+                    const mdAttempt = baseMd.clone();
+                    try {
+                        const promise = auth.authenticate(mdAttempt, timeoutMs, authOptions);
+                        if (timeoutMs !== undefined) {
+                            await (0, cancelable_1.withTimeout)(promise, timeoutMs);
+                        }
+                        else {
+                            await promise;
+                        }
+                        aLog.debug('Authentication successful');
+                        // Within this authenticated window, run the request with internal retries for requestTimeout
+                        const attemptDeadline = new Date(Math.min(Date.now() + requestTimeout, overallDeadline.getTime()));
+                        runAttempt(0, mdAttempt, attemptDeadline);
+                        return;
+                    }
+                    catch (e) {
+                        const canRetry = typeof auth.canRetry === 'function' ? auth.canRetry(e, authOptions) : false;
+                        const stillLeft = timeLeftMs(overallDeadline);
+                        aLog.error('Authentication error', { err: e, canRetry, stillLeft });
+                        if (!canRetry || (stillLeft !== undefined && stillLeft <= 0)) {
+                            // Synthesize UNAUTHENTICATED error
+                            const message = (() => {
+                                if (typeof e === 'string')
+                                    return e;
+                                if (e && typeof e === 'object') {
+                                    const m = e.message;
+                                    if (typeof m === 'string')
+                                        return m;
+                                }
+                                return 'authentication failed';
+                            })();
+                            const baseErr = Object.assign(new Error(message), {
+                                code: index_1.Code.UNAUTHENTICATED.code,
+                                details: message,
+                                metadata: new grpc_js_1.Metadata(),
+                            });
+                            const st = index_1.Status.create({
+                                code: index_1.Code.UNAUTHENTICATED.code,
+                                message,
+                                details: [],
+                            });
+                            this._resolveStatus(st);
+                            reject(new error_1.NebiusGrpcError(baseErr, st));
+                            return;
+                        }
+                        // else retry auth loop
+                    }
+                }
+            };
+            // Kick off
+            startAuthorizedFlow().catch((err) => {
+                // Safety net: if something throws synchronously above
+                try {
+                    if (err instanceof error_1.NebiusGrpcError && err.status)
+                        this._resolveStatus(err.status);
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(err);
+            });
+        });
+    }
+    then(onfulfilled, onrejected) {
+        return this.result.then(onfulfilled, onrejected);
+    }
+    [logging_1.custom]() {
+        let ret = `Request(${this.serviceName}/${this.methodName}@${this.addr}`;
+        if (this._maybeReqId)
+            ret += ` requestId=${this._maybeReqId}`;
+        if (this._maybeTraceId)
+            ret += ` traceId=${this._maybeTraceId}`;
+        if (this._maybeStatus)
+            ret += ` status=${this._maybeStatus.code}`;
+        return ret + ')';
+    }
+    [logging_1.customJson]() {
+        const base = {
+            service: this.serviceName,
+            method: this.methodName,
+            address: this.addr,
+        };
+        if (this._maybeReqId)
+            base.requestId = this._maybeReqId;
+        if (this._maybeTraceId)
+            base.traceId = this._maybeTraceId;
+        if (this._maybeStatus)
+            base.status = (0, logging_1.inspectJson)(this._maybeStatus);
+        return base;
+    }
+    _safeResolveIdsFromMd(md) {
+        const reqId = mdGetString(md, 'x-request-id') || '';
+        const traceId = mdGetString(md, 'x-trace-id') || '';
+        if (reqId) {
+            this._maybeReqId = reqId;
+            this._resolveReqId(reqId);
+        }
+        if (traceId) {
+            this._maybeTraceId = traceId;
+            this._resolveTraceId(traceId);
+        }
+        if (reqId || traceId) {
+            this.logger = this.logger.withFields({
+                requestId: this._maybeReqId,
+                traceId: this._maybeTraceId,
+            });
+            this.logger.debug('Resolved request/trace IDs from metadata');
+        }
+    }
+    _isRetriableError(err) {
+        // Network/system-level errors
+        const sysCode = (err && err.code);
+        if (typeof sysCode === 'string') {
+            const transientErrnos = new Set([
+                'ECONNRESET',
+                'ECONNREFUSED',
+                'EAI_AGAIN',
+                'ETIMEDOUT',
+                'ENOTFOUND',
+                'EHOSTUNREACH',
+                'EPIPE',
+            ]);
+            if (transientErrnos.has(sysCode)) {
+                this.logger.trace('Error is a transient system error', { sys_code: sysCode });
+                return true;
+            }
+        }
+        // gRPC codes
+        const grpcCode = typeof sysCode === 'number' ? sysCode : err?.code;
+        if (grpcCode !== undefined && exports.DefaultRetriableCodes.includes(index_1.Code.fromNumber(grpcCode))) {
+            this.logger.trace('Error has retriable gRPC status code', { grpc_code: grpcCode });
+            return true;
+        }
+        // Our wrapped NebiusGrpcError may carry serviceErrors with retryType
+        const seList = err?.serviceErrors || undefined;
+        if (Array.isArray(seList)) {
+            for (const se of seList) {
+                if (se.retryType === index_2.ServiceError_RetryType.CALL) {
+                    this.logger.trace('Error has retriable service error', { service_error: se });
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    // Allow callers to cancel the in-flight request and prevent further retries
+    cancel(reason) {
+        if (this._canceled) {
+            this.logger.trace('Request already canceled', { reason });
+            return;
+        }
+        this._canceled = true;
+        this.logger.debug('Cancelling request', { reason });
+        // Cancel any tracked calls and detach listeners to help GC
+        for (const c of this._calls) {
+            try {
+                this.logger.trace('Cancelling call', { call: c });
+                c.cancel();
+                c.removeAllListeners();
+            }
+            catch (err) {
+                this.logger.warn('Error cancelling call', { err });
+            }
+        }
+        this.logger.trace('All calls cancelled, clearing tracked calls');
+        this._calls.clear();
+    }
+}
+exports.Request = Request;
+// Helper: get first string value from metadata by key
+function mdGetString(md, key) {
+    if (!md)
+        return undefined;
+    const values = md.get(key);
+    for (const v of values) {
+        if (typeof v === 'string')
+            return v;
+        if (v instanceof Buffer)
+            return v.toString('utf8');
+    }
+    return undefined;
+}
+// Decode google.rpc.Status from grpc error metadata
+function decodeStatusFromError(err) {
+    try {
+        const bin = err.metadata?.get('grpc-status-details-bin');
+        if (!bin || bin.length === 0)
+            return undefined;
+        const first = bin[0];
+        const bytes = first instanceof Buffer
+            ? new Uint8Array(first)
+            : typeof first === 'string'
+                ? Buffer.from(first, 'base64')
+                : undefined;
+        if (!bytes)
+            return undefined;
+        return index_1.Status.decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+function decodeStatusFromStatusEvent(s) {
+    if (!s)
+        return index_1.Status.create({ code: index_1.Code.UNKNOWN.code, message: '', details: [] });
+    try {
+        const bin = s.metadata?.get('grpc-status-details-bin');
+        if (bin && bin.length > 0) {
+            const first = bin[0];
+            const bytes = first instanceof Buffer
+                ? new Uint8Array(first)
+                : typeof first === 'string'
+                    ? Buffer.from(first, 'base64')
+                    : undefined;
+            if (bytes)
+                return index_1.Status.decode(bytes);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return index_1.Status.create({
+        code: (s.code ?? index_1.Code.UNKNOWN.code),
+        message: s.details ?? '',
+        details: [],
+    });
+}
+// Inject parentId based on method name and sdk-provided profileParentId
+// any is necessary because here we patch all requests duck-style
+function injectParentIdIfNeeded(methodName, profileParentId, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+req, logger) {
+    if (!profileParentId) {
+        logger.trace('No profile parentId available, skipping injection');
+        return;
+    }
+    if (!req || typeof req !== 'object') {
+        logger.trace('Request is not an object, skipping parentId injection');
+        return;
+    }
+    const m = (methodName || '').toLowerCase();
+    if (m === 'list' || m === 'getbyname') {
+        if (Object.prototype.hasOwnProperty.call(req, 'parentId')) {
+            if (req.parentId === '' || req.parentId === undefined || req.parentId === null) {
+                logger.trace('List/GetByName request missing parentId, injecting from profile');
+                req.parentId = profileParentId;
+            }
+        }
+        return;
+    }
+    if (m !== 'update') {
+        const md = req.metadata;
+        if (md && typeof md === 'object' && Object.prototype.hasOwnProperty.call(md, 'parentId')) {
+            if (md.parentId === '' || md.parentId === undefined || md.parentId === null) {
+                logger.trace('Request with metadata missing parentId, injecting from profile');
+                md.parentId = profileParentId;
+            }
+        }
+    }
+    else {
+        logger.trace('Update method, skipping parentId injection');
+    }
+}
+//# sourceMappingURL=request.js.map