@oneuptime/common 14.0.10 → 14.0.11

package/build/dist/Server/Utils/EditionEnforcement.js

@@ -1,60 +1,33 @@
 import EnterpriseEdition from "../Enterprise/EnterpriseEdition";
 import EnterpriseFeature from "../Enterprise/EnterpriseFeature";
-import { ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS, ENTERPRISE_LICENSE_TRIAL_PERIOD_IN_DAYS, } from "../Enterprise/EnterpriseLicenseSnapshot";
 import logger from "./Logger";
-import PaymentRequiredException from "../../Types/Exception/PaymentRequiredException";
 /*
- * Which enterprise identity controls are live in this process.
+ * Which enterprise SCIM controls are live in this process.
  *
- * Every answer here follows the RUNTIME state of the feature behind it
- * (EnterpriseEdition.isFeatureActive): SSO for the SSO requirements, the
- * SAML/OIDC sign-in routes and the provider listings, SCIM for the SCIM Push
- * Groups team locks. A feature is active when the Enterprise Edition is loaded
- * and, with billing off, its license covers the feature (valid, in the grace
- * period after it expired, or - with no license - inside the trial).
+ * The answer follows the RUNTIME state of SCIM
+ * (EnterpriseEdition.isFeatureActive(SCIM)): it is active when the Enterprise
+ * Edition is loaded and, with billing off, its license covers SCIM (valid, in
+ * the grace period after it expired, or - with no license - inside the
+ * trial).
  *
- * The controls are relaxed where they cannot work:
- *   - on the Community Edition, which has no SAML/OIDC sign-in routes and no
- *     SCIM endpoints;
- *   - on an Enterprise install whose license has lapsed, where those routes
- *     refuse (ee/Server/Identity).
- * Enforcing a leftover "Require SSO for login" there would lock every user
- * out, and a leftover SCIM Push Groups lock would leave teams nobody can
- * manage. Users sign in with their password instead (users who only ever used
- * SSO reset it). The configuration itself is kept untouched - reads made for
- * a caller report the requirement as off, and a caller's write can neither
- * switch it off nor set it meanwhile (guardSsoRequirementWrite) - so running
- * the Enterprise Edition again (with a valid license, or during its trial or
- * grace period), or renewing the license, restores enforcement without a
- * restart.
+ * The SCIM Push Groups team locks are relaxed where they cannot work:
+ *   - on the Community Edition, which has no SCIM endpoints;
+ *   - on an Enterprise install whose license does not cover SCIM right now,
+ *     where those endpoints refuse (ee/Server/Identity).
+ * A leftover lock there would leave teams nobody can manage, because the
+ * identity provider that owns them cannot reach OneUptime. The SCIM
+ * configuration itself is kept untouched, so running the Enterprise Edition
+ * again (with a valid license, or during its trial or grace period), or
+ * renewing the license, restores the locks without a restart.
+ *
+ * Single sign-on is not decided here: it is part of the Community Edition,
+ * and a configured "Require SSO for login" is enforced in every edition.
  *
  * Failure direction: an error while deciding answers "enforce", and an
  * unknown license state counts as active (see isFeatureActive), so a read
- * error never switches a control off.
+ * error never switches a lock off.
  */
-class EditionEnforcement {
-    /*
-     * Whether configured SSO requirements - a project's requireSsoForLogin (and
-     * its required provider), the instance-wide requireSsoForLogin and a status
-     * page's requireSsoForLogin - are enforced.
-     */
-    static isSsoEnforced() {
-        try {
-            return EnterpriseEdition.isFeatureActive(EnterpriseFeature.SSO);
-        }
-        catch (err) {
-            logger.error("EditionEnforcement: could not tell whether SSO is enforced; enforcing it.");
-            logger.error(err);
-            return true;
-        }
-    }
-    // A configured SSO requirement that is also enforced in this process.
-    static isSsoRequired(configuredRequirement) {
-        if (!configuredRequirement) {
-            return false;
-        }
-        return EditionEnforcement.isSsoEnforced();
-    }
+export default class EditionEnforcement {
     /*
      * Whether SCIM Push Groups owns team membership: while a project's SCIM
      * configuration has Push Groups on, teams and team members can only be
@@ -72,116 +45,5 @@ class EditionEnforcement {
             return true;
         }
     }
-    /*
-     * Whether the SAML/OIDC sign-in routes answer right now. Provider listings
-     * (the lists a sign-in page offers) are empty when they do not, so no client
-     * sends a user into a route that answers 404 (Community Edition) or refuses
-     * because the license lapsed (Enterprise Edition).
-     */
-    static areSsoRoutesServed() {
-        try {
-            return EnterpriseEdition.isFeatureActive(EnterpriseFeature.SSO);
-        }
-        catch (err) {
-            logger.error("EditionEnforcement: could not tell whether the SSO routes are served; serving them.");
-            logger.error(err);
-            return true;
-        }
-    }
-    /*
-     * Whether a read should report the EFFECTIVE SSO requirement (false)
-     * instead of the stored one. Clients - the mobile app in particular, whose
-     * store builds cannot be patched - decide from these columns whether to
-     * start an SSO flow, and while SSO is not active that flow does not exist
-     * (Community Edition) or refuses (lapsed license).
-     *
-     * Only reads made for a caller are masked. Internal (root) reads see the
-     * stored value, and a read never writes, so the configuration is intact
-     * when SSO is active again. The write half is guardSsoRequirementWrite.
-     */
-    static shouldMaskSsoRequirementOnRead(props) {
-        if (!props || props.isRoot) {
-            return false;
-        }
-        return !EditionEnforcement.isSsoEnforced();
-    }
-    /*
-     * The write half of shouldMaskSsoRequirementOnRead, for the services'
-     * onBeforeUpdate. A caller whose reads are masked has only ever seen the
-     * requirement as off (no required provider), so what it writes to those
-     * columns cannot be taken at face value: a settings form, or an API client
-     * doing a read-modify-write, sends back the masked value it read. Saving it
-     * would switch a configured requirement off without anybody deciding to,
-     * and it would stay off once SSO is active again.
-     *
-     * So while this caller's reads are masked:
-     *   - a write of the masked value (false, or no provider) is dropped from
-     *     `data`, and the stored requirement is kept;
-     *   - a write that would set a requirement (true, or a provider) is
-     *     refused: it could neither be seen nor enforced until SSO is active;
-     *   - a write that is left with nothing else to save is refused with the
-     *     same explanation, rather than reporting a save that did not happen.
-     *
-     * Root writes, and every write while SSO is active, are left alone.
-     * Mutates `data`. Throws PaymentRequiredException.
-     */
-    static guardSsoRequirementWrite(input) {
-        if (!EditionEnforcement.shouldMaskSsoRequirementOnRead(input.props)) {
-            return;
-        }
-        const writtenColumns = input.columns.filter((column) => {
-            return input.data[column] !== undefined;
-        });
-        if (writtenColumns.length === 0) {
-            return;
-        }
-        const setsRequirement = writtenColumns.some((column) => {
-            return !EditionEnforcement.isMaskedSsoRequirementValue(input.data[column]);
-        });
-        if (setsRequirement) {
-            throw EditionEnforcement.createSsoRequirementUnchangeableException();
-        }
-        for (const column of writtenColumns) {
-            delete input.data[column];
-        }
-        /*
-         * `data` is the plain update onBeforeUpdate receives (a model instance
-         * has already been reduced to its set columns by
-         * DatabaseService.sanitizeUpdateData); a key left undefined writes
-         * nothing, so it does not count.
-         */
-        const hasOtherColumns = Object.keys(input.data).some((key) => {
-            return input.data[key] !== undefined;
-        });
-        if (!hasOtherColumns) {
-            throw EditionEnforcement.createSsoRequirementUnchangeableException();
-        }
-    }
-    // What a masked read reports for a requirement column: false or null.
-    static isMaskedSsoRequirementValue(value) {
-        return value === false || value === null;
-    }
-    static createSsoRequirementUnchangeableException() {
-        let isEnterpriseEditionLoaded = true;
-        try {
-            isEnterpriseEditionLoaded = EnterpriseEdition.isLoaded();
-        }
-        catch (err) {
-            logger.error(err);
-        }
-        return new PaymentRequiredException(isEnterpriseEditionLoaded
-            ? EditionEnforcement.SSO_REQUIREMENT_UNCHANGEABLE_LICENSE_MESSAGE
-            : EditionEnforcement.SSO_REQUIREMENT_UNCHANGEABLE_COMMUNITY_MESSAGE);
-    }
 }
-// Why guardSsoRequirementWrite refuses a write, on the Community Edition.
-EditionEnforcement.SSO_REQUIREMENT_UNCHANGEABLE_COMMUNITY_MESSAGE = 'Single sign-on is part of the OneUptime Enterprise Edition and this server runs the Community Edition, so "Require SSO for login" shows as off, is not enforced and cannot be changed here. ' +
-    `A setting saved earlier is kept, and it is enforced again when this server runs the Enterprise Edition image with a valid license (or during its ${ENTERPRISE_LICENSE_TRIAL_PERIOD_IN_DAYS}-day trial, or the ${ENTERPRISE_LICENSE_GRACE_PERIOD_IN_DAYS}-day grace period after a license expires).`;
-/*
- * Why guardSsoRequirementWrite refuses a write, on an Enterprise install
- * whose license does not cover SSO right now.
- */
-EditionEnforcement.SSO_REQUIREMENT_UNCHANGEABLE_LICENSE_MESSAGE = 'Single sign-on has stopped because the OneUptime Enterprise license is missing, expired or does not include SSO, so "Require SSO for login" shows as off, is not enforced and cannot be changed. ' +
-    "The saved setting is kept, and it is enforced again as soon as a master admin activates or renews the license from the edition label in the Admin Dashboard header.";
-export default EditionEnforcement;
 //# sourceMappingURL=EditionEnforcement.js.map

package/build/dist/Server/Utils/EditionEnforcement.js.map

@@ -1 +1 @@
-{"version":3,"file":"EditionEnforcement.js","sourceRoot":"","sources":["../../../../Server/Utils/EditionEnforcement.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EditionEnforcement.js","sourceRoot":"","sources":["../../../../Server/Utils/EditionEnforcement.ts"],"names":[],"mappings":"AAAA,OAAO,iBAAiB,MAAM,iCAAiC,CAAC;AAChE,OAAO,iBAAiB,MAAM,iCAAiC,CAAC;AAChE,OAAO,MAAM,MAAM,UAAU,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,OAAO,OAAO,kBAAkB;IACrC;;;;;;OAMG;IACI,MAAM,CAAC,wBAAwB;QACpC,IAAI,CAAC;YACH,OAAO,iBAAiB,CAAC,eAAe,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACnE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CACV,kFAAkF,CACnF,CAAC;YACF,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAClB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/build/dist/Server/Utils/LLM/LLMService.js

@@ -12,7 +12,9 @@ import URL from "../../../Types/API/URL";
 import JSONFunctions from "../../../Types/JSONFunctions";
 import API from "../../../Utils/API";
 import LlmType from "../../../Types/LLM/LlmType";
+import APIException from "../../../Types/Exception/ApiException";
 import BadDataException from "../../../Types/Exception/BadDataException";
+import EgressGuardException, { EgressFailureReason, } from "../../../Types/Exception/EgressGuardException";
 import logger from "../Logger";
 import CaptureSpan from "../Telemetry/CaptureSpan";
 import DataSourceEgressGuard from "../DataSource/EgressGuard";
@@ -44,6 +46,17 @@ const OLLAMA_RESERVED_REQUEST_KEYS = new Set([
     "tools",
     "stream",
 ]);
+/*
+ * Why the egress guard refused a provider URL, in words that do not name the
+ * host. Unreachable stays a single sentence: the guard uses it for both a
+ * failed lookup and a refused address, so they cannot be told apart.
+ */
+const EGRESS_REFUSAL_DESCRIPTIONS = {
+    [EgressFailureReason.InvalidTarget]: "the LLM provider base URL is not a valid http or https URL",
+    [EgressFailureReason.AddressBlocked]: "the LLM provider base URL points to an address OneUptime is not allowed to connect to",
+    [EgressFailureReason.ResolutionFailed]: "the LLM provider's host name could not be resolved",
+    [EgressFailureReason.Unreachable]: "the LLM provider could not be reached",
+};
 class LLMService {
     static getAdaptationCacheKey(config, modelName) {
         return `${config.llmType}|${config.baseUrl || ""}|${modelName}`;
@@ -394,17 +407,6 @@ class LLMService {
         }
         return Math.max(this.DEFAULT_RETRY_DEADLINE_IN_MS, timeoutInMs * this.MIN_FULL_TIMEOUT_ATTEMPTS_WITHIN_DEADLINE);
     }
-    /**
-     * POST an OpenAI-style chat completion, reshaping and retrying when the
-     * endpoint rejects a generation parameter it does not support.
-     *
-     * This is error-driven rather than model-driven on purpose. Azure sends the
-     * deployment name in `model`, and operators name deployments whatever they
-     * like, so there is no reliable way to know up front whether a deployment is
-     * a reasoning model. The provider itself is the only authority, and it names
-     * the offending parameter in the 400 — one parameter per response, hence the
-     * loop.
-     */
     /*
      * Request options for a call to a tenant-configured LLM endpoint.
      *
@@ -420,13 +422,58 @@ class LLMService {
      * around it. Private ranges stay reachable on self-hosted installs, because
      * a self-hosted Ollama on 10.x is the documented deployment.
      */
-    static async buildGuardedRequestOptions(requestUrl, options) {
-        const { httpAgent, httpsAgent } = await DataSourceEgressGuard.assertUrlAllowedAndPin(requestUrl, {
-            targetLabel: "LLM provider",
-        });
-        return Object.assign(Object.assign({}, options), { doNotFollowRedirects: true, httpAgent,
-            httpsAgent });
+    static async buildGuardedRequestOptions(data) {
+        let pinnedAgents;
+        try {
+            pinnedAgents = await DataSourceEgressGuard.assertUrlAllowedAndPin(data.requestUrl, {
+                targetLabel: "LLM provider",
+            });
+        }
+        catch (error) {
+            // The guard's refusal names the host it refused.
+            throw this.toAddressFreeProviderError({
+                providerName: data.providerName,
+                error: error,
+                logAttributes: data.logAttributes,
+            });
+        }
+        return Object.assign(Object.assign({}, data.options), { doNotFollowRedirects: true, httpAgent: pinnedAgents.httpAgent, httpsAgent: pinnedAgents.httpsAgent });
+    }
+    /*
+     * POST to a provider. A request that gets no response at all is thrown by
+     * API as "Request failed to <url>. <reason>", so it is rethrown without the
+     * address; a provider that answers with an error status is returned as an
+     * HTTPErrorResponse, as before.
+     */
+    static async postToProvider(data) {
+        try {
+            return await API.post({
+                url: URL.fromString(data.requestUrl),
+                data: data.body,
+                headers: data.headers,
+                options: data.options,
+            });
+        }
+        catch (error) {
+            throw this.toAddressFreeProviderError({
+                providerName: data.providerName,
+                error: error,
+                timeoutInMs: data.options.timeout,
+                logAttributes: data.logAttributes,
+            });
+        }
     }
+    /**
+     * POST an OpenAI-style chat completion, reshaping and retrying when the
+     * endpoint rejects a generation parameter it does not support.
+     *
+     * This is error-driven rather than model-driven on purpose. Azure sends the
+     * deployment name in `model`, and operators name deployments whatever they
+     * like, so there is no reliable way to know up front whether a deployment is
+     * a reasoning model. The provider itself is the only authority, and it names
+     * the offending parameter in the 400 — one parameter per response, hence the
+     * loop.
+     */
     static async postOpenAIChatCompletion(data) {
         let adaptation = this.getInitialRequestAdaptation(data.config, data.modelName);
         /*
@@ -442,10 +489,15 @@ class LLMService {
          * re-posts to the same URL, so re-resolving per attempt would only add
          * DNS round trips (and a rebind window between them).
          */
-        const requestOptions = await this.buildGuardedRequestOptions(data.requestUrl, this.buildRequestPolicy({
-            request: data.request,
-            defaultTimeoutInMs: 120000,
-        }));
+        const requestOptions = await this.buildGuardedRequestOptions({
+            providerName: data.providerName,
+            requestUrl: data.requestUrl,
+            options: this.buildRequestPolicy({
+                request: data.request,
+                defaultTimeoutInMs: 120000,
+            }),
+            logAttributes: data.logAttributes,
+        });
         const post = () => {
             const body = this.buildOpenAIRequestBody(data.modelName, data.request, adaptation);
             if (body["max_completion_tokens"] !== undefined) {
@@ -454,11 +506,13 @@ class LLMService {
             else if (body["max_tokens"] !== undefined) {
                 attemptedTokenLimitParams.add(TokenLimitParam.MaxTokens);
             }
-            return API.post({
-                url: URL.fromString(data.requestUrl),
-                data: body,
+            return this.postToProvider({
+                providerName: data.providerName,
+                requestUrl: data.requestUrl,
+                body: body,
                 headers: data.headers,
                 options: requestOptions,
+                logAttributes: data.logAttributes,
             });
         };
         let response = await post();
@@ -537,6 +591,73 @@ class LLMService {
         }
         throw new BadDataException(`${data.providerName} API request failed. Review the provider configuration and try again.`);
     }
+    /*
+     * The error for a provider that could not be reached, rebuilt so that it
+     * never names the provider's address.
+     *
+     * API reports a request that got no response as "Request failed to <url>.
+     * <reason>", and the egress guard names the host it refused. Those messages
+     * end up in LlmLog, chat replies and the investigation panel, which every
+     * project member can read, and for the global provider that exposes an LLM
+     * server tenants were never given. So the message says what went wrong but
+     * not where, and the operator gets the original in the server log.
+     *
+     * The exception type (and the guard's reason) is kept, so status codes and
+     * retry classification are unchanged. The original error is not attached:
+     * an AxiosError carries the URL and the request headers, credentials
+     * included.
+     */
+    static toAddressFreeProviderError(data) {
+        logger.error(`${data.providerName} API request failed before the provider responded: ${data.error instanceof Error ? data.error.message : String(data.error)}`, data.logAttributes);
+        if (data.error instanceof EgressGuardException) {
+            return new EgressGuardException(`${data.providerName} API request failed: ${EGRESS_REFUSAL_DESCRIPTIONS[data.error.reason]}.`, data.error.reason);
+        }
+        return new APIException(`${data.providerName} API request failed: ${this.describeTransportFailure(data.error, data.timeoutInMs)}.`);
+    }
+    static describeTransportFailure(error, timeoutInMs) {
+        // API wraps the transport error, and its code is what says what happened.
+        const cause = error instanceof APIException && error.error ? error.error : error;
+        const rawCode = cause && typeof cause === "object"
+            ? cause.code
+            : undefined;
+        const code = typeof rawCode === "string" ? rawCode : "";
+        const message = (cause instanceof Error ? cause.message : String(cause)).toLowerCase();
+        // axios' own per-attempt timeout: "timeout of 120000ms exceeded".
+        if (code === "ECONNABORTED" || message.includes("timeout of")) {
+            if (!timeoutInMs) {
+                return "the LLM provider did not respond in time";
+            }
+            const seconds = Math.round(timeoutInMs / 1000);
+            return `the LLM provider did not respond within ${seconds >= 1
+                ? `${seconds} second${seconds === 1 ? "" : "s"}`
+                : `${timeoutInMs} ms`}`;
+        }
+        if (code === "ETIMEDOUT" || code === "ESOCKETTIMEDOUT") {
+            return "the connection to the LLM provider timed out";
+        }
+        if (code === "ECONNREFUSED") {
+            return "the LLM provider refused the connection";
+        }
+        if (code === "ECONNRESET" ||
+            code === "EPIPE" ||
+            message.includes("socket hang up")) {
+            return "the LLM provider closed the connection before responding";
+        }
+        if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+            return "the LLM provider's host name could not be resolved";
+        }
+        if (code === "EHOSTUNREACH" ||
+            code === "ENETUNREACH" ||
+            code === "EADDRNOTAVAIL") {
+            return "the LLM provider could not be reached over the network";
+        }
+        // Certificate and handshake failures, e.g. CERT_HAS_EXPIRED.
+        const tlsFailureCodeRegex = /^(CERT_|ERR_TLS_|ERR_SSL_|EPROTO$)|SELF_SIGNED|UNABLE_TO_/;
+        if (tlsFailureCodeRegex.test(code)) {
+            return "a secure connection to the LLM provider could not be established";
+        }
+        return "the LLM provider could not be reached";
+    }
     /*
      * Build the chat completions URL for an OpenAI-compatible server from the
      * configured base URL. Users enter the base URL in a few different ways, and
@@ -641,7 +762,12 @@ class LLMService {
             defaultBaseUrls[config.llmType] ||
             "https://api.openai.com/v1";
         const modelName = config.modelName || defaultModels[config.llmType] || "gpt-5.1";
+        const logAttributes = {
+            llmType: config.llmType,
+            modelName: modelName,
+        };
         const response = await this.postOpenAIChatCompletion({
+            providerName: config.llmType.toString(),
             requestUrl: this.buildOpenAICompatibleChatCompletionsUrl(baseUrl),
             headers: Object.assign({ "Content-Type": "application/json" }, (config.apiKey
                 ? { Authorization: `Bearer ${config.apiKey}` }
@@ -649,11 +775,8 @@ class LLMService {
             config: config,
             modelName: modelName,
             request: request,
+            logAttributes: logAttributes,
         });
-        const logAttributes = {
-            llmType: config.llmType,
-            modelName: modelName,
-        };
         if (response instanceof HTTPErrorResponse) {
             this.throwProviderHTTPError({
                 providerName: config.llmType.toString(),
@@ -693,7 +816,12 @@ class LLMService {
          */
         const modelName = config.modelName || "gpt-4o";
         const requestUrl = LLMService.buildAzureOpenAIChatCompletionsUrl(config.baseUrl);
+        const logAttributes = {
+            llmType: config.llmType,
+            modelName: modelName,
+        };
         const response = await this.postOpenAIChatCompletion({
+            providerName: "Azure OpenAI",
             requestUrl: requestUrl,
             headers: {
                 "api-key": config.apiKey,
@@ -702,11 +830,8 @@ class LLMService {
             config: config,
             modelName: modelName,
             request: request,
+            logAttributes: logAttributes,
         });
-        const logAttributes = {
-            llmType: config.llmType,
-            modelName: modelName,
-        };
         if (response instanceof HTTPErrorResponse) {
             this.throwProviderHTTPError({
                 providerName: "Azure OpenAI",
@@ -850,23 +975,30 @@ class LLMService {
             requestData["tools"] = anthropicTools;
         }
         const anthropicRequestUrl = `${baseUrl}/messages`;
-        const response = await API.post({
-            url: URL.fromString(anthropicRequestUrl),
-            data: requestData,
+        const anthropicLogAttributes = {
+            llmType: config.llmType,
+            modelName: modelName,
+        };
+        const response = await this.postToProvider({
+            providerName: "Anthropic",
+            requestUrl: anthropicRequestUrl,
+            body: requestData,
             headers: {
                 "x-api-key": config.apiKey,
                 "anthropic-version": "2023-06-01",
                 "Content-Type": "application/json",
             },
-            options: await this.buildGuardedRequestOptions(anthropicRequestUrl, this.buildRequestPolicy({
-                request: request,
-                defaultTimeoutInMs: 120000,
-            })),
+            options: await this.buildGuardedRequestOptions({
+                providerName: "Anthropic",
+                requestUrl: anthropicRequestUrl,
+                options: this.buildRequestPolicy({
+                    request: request,
+                    defaultTimeoutInMs: 120000,
+                }),
+                logAttributes: anthropicLogAttributes,
+            }),
+            logAttributes: anthropicLogAttributes,
         });
-        const anthropicLogAttributes = {
-            llmType: config.llmType,
-            modelName: modelName,
-        };
         if (response instanceof HTTPErrorResponse) {
             this.throwProviderHTTPError({
                 providerName: "Anthropic",
@@ -1029,21 +1161,28 @@ class LLMService {
             }
         }
         const ollamaRequestUrl = `${config.baseUrl}/api/chat`;
-        const response = await API.post({
-            url: URL.fromString(ollamaRequestUrl),
-            data: requestData,
-            headers: {
-                "Content-Type": "application/json",
-            },
-            options: await this.buildGuardedRequestOptions(ollamaRequestUrl, this.buildRequestPolicy({
-                request: request,
-                defaultTimeoutInMs: 300000, // Ollama may be slower
-            })),
-        });
         const ollamaLogAttributes = {
             llmType: config.llmType,
             modelName: modelName,
         };
+        const response = await this.postToProvider({
+            providerName: "Ollama",
+            requestUrl: ollamaRequestUrl,
+            body: requestData,
+            headers: {
+                "Content-Type": "application/json",
+            },
+            options: await this.buildGuardedRequestOptions({
+                providerName: "Ollama",
+                requestUrl: ollamaRequestUrl,
+                options: this.buildRequestPolicy({
+                    request: request,
+                    defaultTimeoutInMs: 300000, // Ollama may be slower
+                }),
+                logAttributes: ollamaLogAttributes,
+            }),
+            logAttributes: ollamaLogAttributes,
+        });
         if (response instanceof HTTPErrorResponse) {
             this.throwProviderHTTPError({
                 providerName: "Ollama",